email.message: بازنمایی یک پیام ایمیل

کد منبع: Lib/email/message.py

---

اضافه شده در نسخه‌ی 3.6: [1]

کلاس مرکزی در بسته‌ی email، کلاس EmailMessage است که از ماژول email.message ایمپورت می‌شود. این کلاس، کلاس پایه‌ی مدل شیء email است. EmailMessage کارکرد اصلی را برای تنظیم و پرس‌وجوی فیلدهای سرآیند، دسترسی به بدنه‌های پیام و ایجاد یا تغییر پیام‌های ساختاریافته فراهم می‌کند.

یک پیام ایمیلی از سرآیند‌ها و یک بار تشکیل شده است (که به آن محتوا نیز گفته می‌شود). سرآیند‌ها نام‌ها و مقدارهای فیلد به سبک RFC 5322 یا RFC 6532 هستند، که در آن‌ها نام فیلد و مقدار با یک دونقطه از هم جدا می‌شوند. دونقطه نه بخشی از نام فیلد است و نه بخشی از مقدار فیلد. بار ممکن است یک پیام متنی ساده، یا یک شیء دودویی، یا دنباله‌ای ساختارمند از زیرپیام‌ها باشد که هرکدام مجموعه‌ای از سرآیند‌ها و بار خود را دارند. نوع اخیر بار با نوع MIME پیام، مانند multipart/* یا message/rfc822، مشخص می‌شود.

مدل مفهومی ارائه‌شده توسط یک شیء EmailMessage، به‌صورت یک دیکشنری مرتب از سرآیند‌ها همراه با یک بار است که بدنه‌ی پیام مطابق RFC 5322 را نشان می‌دهد و ممکن است فهرستی از اشیاء EmailMessage فرعی باشد. علاوه بر متدهای معمول دیکشنری برای دسترسی به نام‌ها و مقادیر سرآیند‌ها، متدهایی برای دسترسی به اطلاعات تخصصی از سرآیند‌ها (برای مثال نوع محتوای MIME)، برای انجام عملیات بر روی بار، برای تولید نسخه‌ای سریال‌شده از پیام، و برای پیمایش بازگشتی بر روی درخت اشیاء وجود دارد.

رابط دیکشنری‌مانند EmailMessage با نام‌های سرآیند اندیس‌دهی می‌شود؛ این نام‌ها باید مقادیر ASCII باشند. مقادیر دیکشنری، رشته‌هایی هستند که چند متد اضافی دارند. سرآیندها با حفظ حالت حروف ذخیره و بازگردانده می‌شوند، اما نام‌های فیلد بدون حساسیت به حالت حروف تطبیق داده می‌شوند. کلیدها مرتب هستند، اما برخلاف یک دیکشنری واقعی، ممکن است کلیدهای تکراری وجود داشته باشد. متدهای اضافی برای کار با سرآیندهایی که کلیدهای تکراری دارند ارائه شده‌اند.

بار در مورد اشیاء پیام ساده، یا یک شیء رشته یا bytes است، یا در مورد اشیاء پیامِ اسناد نگهدارنده‌ی MIME مانند multipart/* و message/rfc822، فهرستی از اشیاء EmailMessage است.

class email.message.EmailMessage(policy=default)

اگر policy مشخص شده باشد، از قوانین مشخص‌شده توسط آن برای به‌روزرسانی و سریال‌سازی بازنمایی پیام استفاده می‌شود. اگر policy تنظیم نشده باشد، از سیاست default استفاده می‌شود، که از قوانین RFCهای ایمیل پیروی می‌کند، به‌جز در مورد پایان سطرهای (به‌جای \r\n مورد الزام RFC، از پایان سطرهای استاندارد پایتون یعنی \n استفاده می‌کند). برای اطلاعات بیشتر، مستندات policy را ببینید. [2]

as_string(unixfrom=False, maxheaderlen=None, policy=None)

کل پیام را به‌صورت یک رشته‌ی مسطح برمی‌گرداند. هنگامی که آرگومان اختیاری unixfrom درست باشد، سرآیند پاکت (envelope header) در رشته‌ی برگردانده‌شده گنجانده می‌شود. مقدار پیش‌فرض unixfrom برابر False است. برای سازگاری عقب‌رو با کلاس پایه‌ی Message، maxheaderlen پذیرفته می‌شود، اما مقدار پیش‌فرض آن None است، که به این معناست که به‌طور پیش‌فرض طول خط توسط max_line_length سیاست کنترل می‌شود. می‌توان از آرگومان policy برای نادیده گرفتن سیاست پیش‌فرضی که از نمونه‌ی پیام گرفته می‌شود استفاده کرد. این می‌تواند برای کنترل برخی از قالب‌بندی‌های تولیدشده توسط متد به کار رود، زیرا policy مشخص‌شده به Generator ارسال می‌شود.

تسطیح پیام ممکن است باعث ایجاد تغییراتی در EmailMessage شود، اگر برای تکمیل تبدیل به یک رشته نیاز باشد مقادیر پیش‌فرض پر شوند (برای مثال، ممکن است مرزهای MIME تولید یا اصلاح شوند).

توجه داشته باشید که این متد برای راحتی کار ارائه شده است و ممکن است مفیدترین روش برای سریال‌سازی پیام‌ها در برنامه شما نباشد، به‌ویژه اگر با چندین پیام سروکار دارید. برای یک API انعطاف‌پذیرتر جهت سریال‌سازی پیام‌ها، email.generator.Generator را ببینید. همچنین توجه داشته باشید که این متد، وقتی utf8 برابر False باشد (که مقدار پیش‌فرض است)، محدود به تولید پیام‌هایی است که به‌صورت «7 bit clean» سریال‌سازی شده‌اند.

تغییر یافته در نسخه‌ی 3.6: رفتار پیش‌فرض زمانی که maxheaderlen مشخص‌نشده باشد، از پیش‌فرض ۰ به پیش‌فرض مقدار max_line_length از سیاست تغییر کرده است.

__str__()

معادل as_string(policy=self.policy.clone(utf8=True)) است و به str(msg) اجازه می‌دهد رشته‌ای حاوی پیام سریال‌شده در قالبی خوانا تولید کند.

تغییر یافته در نسخه‌ی 3.4: این متد تغییر یافت تا از utf8=True استفاده کند، در نتیجه بازنمایی پیامی شبیه به RFC 6531 تولید می‌کند، به‌جای آنکه نام مستعار مستقیمی برای as_string() باشد.

as_bytes(unixfrom=False, policy=None)

کل پیام را به‌صورت یک شیء بایتی مسطح‌شده برمی‌گرداند. هنگامی که آرگومان اختیاری unixfrom مقدار true داشته باشد، سرآیند پاکت در رشته برگردانده‌شده گنجانده می‌شود. مقدار پیش‌فرض unixfrom برابر False است. می‌توان از آرگومان policy برای لغو سیاست پیش‌فرض به‌دست‌آمده از نمونه پیام استفاده کرد. از این می‌توان برای کنترل بخشی از قالب‌بندی تولیدشده توسط متد استفاده کرد، زیرا policy مشخص‌شده به BytesGenerator ارسال خواهد شد.

تسطیح پیام ممکن است باعث ایجاد تغییراتی در EmailMessage شود، اگر برای تکمیل تبدیل به یک رشته نیاز باشد مقادیر پیش‌فرض پر شوند (برای مثال، ممکن است مرزهای MIME تولید یا اصلاح شوند).

توجه داشته باشید که این متد به‌منظور سهولت ارائه شده است و ممکن است مفیدترین روش برای سریال‌سازی پیام‌ها در برنامه شما نباشد، به‌ویژه اگر با چندین پیام سروکار دارید. برای یک API انعطاف‌پذیرتر جهت سریال‌سازی پیام‌ها، email.generator.BytesGenerator را ببینید.

__bytes__()

معادل as_bytes() است. اجازه می‌دهد bytes(msg) یک شیء bytes حاوی پیام سریال‌شده تولید کند.

is_multipart()

اگر بار پیام فهرستی از اشیای sub-EmailMessage باشد، True را برمی‌گرداند، در غیر این صورت False را برمی‌گرداند. هنگامی که is_multipart() مقدار False را برمی‌گرداند، بار باید یک شیء رشته‌ای باشد (که ممکن است یک بار دودویی کدگذاری‌شده با CTE باشد). توجه داشته باشید که برگرداندن True از سوی is_multipart() لزوماً به این معنا نیست که "msg.get_content_maintype() == 'multipart'" مقدار True را برمی‌گرداند. برای مثال، هنگامی که EmailMessage از نوع message/rfc822 باشد، is_multipart مقدار True را برمی‌گرداند.

set_unixfrom(unixfrom)

سرآیند پاکت پیام را روی unixfrom تنظیم کنید، که باید یک رشته باشد. (برای شرح کوتاهی از این سرآیند، mboxMessage را ببینید.)

get_unixfrom()

سرآیند پاکت پیام را بازمی‌گرداند. اگر سرآیند پاکت هرگز تنظیم نشده باشد، مقدار پیش‌فرض آن None است.

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

این تفاوت‌های معنایی عمدی هستند و به سمت سهولت در رایج‌ترین موارد استفاده تمایل دارند.

توجه داشته باشید که در همه موارد، هر سرآیند پاکتی (envelope header) که در پیام وجود دارد، در رابط نگاشت گنجانده نمی‌شود.

__len__()

تعداد کل سرآیندها، از جمله تکراری‌ها را برمی‌گرداند.

__contains__(name)

اگر شیء پیام فیلدی به نام name داشته باشد، True را برمی‌گرداند. تطبیق بدون در نظر گرفتن بزرگی و کوچکی حروف انجام می‌شود و name شامل دونقطه پایانی نمی‌شود. برای عملگر in استفاده می‌شود. برای مثال:

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

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

توجه داشته باشید که اگر فیلد نام‌برده‌شده بیش از یک بار در سرآیند‌های پیام ظاهر شود، دقیقاً اینکه کدام‌یک از مقدارهای آن فیلد برگردانده می‌شود، تعریف‌نشده است. برای دریافت مقدارهای همه سرآیند‌های موجود با نام name از متد get_all() استفاده کنید.

با استفاده از سیاست‌های استاندارد (غیر compat32)، مقدار برگردانده‌شده نمونه‌ای از زیرکلاسی از email.headerregistry.BaseHeader است.

__setitem__(name, val)

یک سرآیند با نام فیلد name و مقدار val به پیام اضافه کنید. این فیلد به پایان سرآیندهای موجود پیام افزوده می‌شود.

توجه داشته باشید که این کار هیچ سرآیند موجودی با نام یکسان را بازنویسی یا حذف نمی‌کند. اگر می‌خواهید اطمینان حاصل کنید که سرآیند جدید، تنها سرآیند موجود در پیام با نام فیلد name است، ابتدا فیلد را حذف کنید، برای مثال:

del msg['subject']
msg['subject'] = 'Python roolz!'

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

__delitem__(name)

تمام موارد فیلد با نام name را از سرآیندهای پیام حذف می‌کند. اگر فیلد نام‌برده در سرآیندها وجود نداشته باشد، هیچ استثنایی پرتاب نمی‌شود.

keys()

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

values()

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

items()

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

get(name, failobj=None)

مقدار فیلد سرآیندِ نام‌برده‌شده را برمی‌گرداند. این با __getitem__() یکسان است، با این تفاوت که اگر سرآیند نام‌برده‌شده وجود نداشته باشد، failobj اختیاری برگردانده می‌شود (مقدار پیش‌فرض failobj None است).

در اینجا چند متد مفید دیگر مرتبط با سرآیند آمده است:

get_all(name, failobj=None)

فهرستی از همه‌ی مقادیر فیلدی با نام name را برمی‌گرداند. اگر هیچ سرآیند‌ای با این نام در پیام وجود نداشته باشد، failobj برگردانده می‌شود (پیش‌فرض None است).

add_header(_name, _value, **_params)

تنظیم سرآیند گسترش‌یافته. این متد مشابه __setitem__() است، با این تفاوت که می‌توان پارامترهای اضافی سرآیند را به‌صورت آرگومان‌های کلیدواژه‌ای ارائه کرد. _name فیلد سرآیندی است که باید افزوده شود و _value مقدار اصلی برای سرآیند است.

برای هر آیتم در دیکشنری آرگومان‌های کلیدواژه‌ای _params، کلید به‌عنوان نام پارامتر در نظر گرفته می‌شود و زیرسطرها به خط تیره تبدیل می‌شوند (زیرا خط تیره در شناسه‌های پایتون غیرمجاز است). معمولاً، پارامتر به‌صورت key="value" اضافه می‌شود، مگر اینکه مقدار None باشد، که در این صورت فقط کلید اضافه می‌شود.

اگر مقدار حاوی نویسه‌های غیر ASCII باشد، می‌توان مجموعه نویسه و زبان را به‌صراحت با تعیین مقدار به‌صورت یک تاپل سه‌تایی در قالب (CHARSET, LANGUAGE, VALUE) کنترل کرد، که در آن CHARSET رشته‌ای است که نام مجموعه نویسه مورد استفاده برای کدگذاری مقدار را مشخص می‌کند، LANGUAGE معمولاً می‌تواند None یا رشته خالی باشد (برای سایر حالت‌ها RFC 2231 را ببینید)، و VALUE مقدار رشته‌ای حاوی نقاط کد غیر ASCII است. اگر یک تاپل سه‌تایی ارسال نشود و مقدار حاوی نویسه‌های غیر ASCII باشد، به‌طور خودکار در قالب RFC 2231 با CHARSET برابر utf-8 و LANGUAGE برابر None کدگذاری می‌شود.

در اینجا مثالی آمده است:

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

این یک سرآیند اضافه می‌کند که به این شکل است

Content-Disposition: attachment; filename="bud.gif"

مثالی از رابط گسترش‌یافته با نویسه‌های غیر ASCII:

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

replace_header(_name, _value)

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

get_content_type()

نوع محتوای پیام را به صورت حروف کوچک و در قالب maintype/subtype برمی‌گرداند. اگر سرآیند Content-Type در پیام وجود نداشته باشد، مقدار بازگشتی از get_default_type() را برمی‌گرداند. اگر سرآیند Content-Type نامعتبر باشد، text/plain را برمی‌گرداند.

(بر اساس RFC 2045، پیام‌ها همیشه یک نوع پیش‌فرض دارند؛ get_content_type() همیشه یک مقدار برمی‌گرداند. RFC 2045 نوع پیش‌فرض یک پیام را text/plain تعریف می‌کند، مگر اینکه داخل یک ظرف multipart/digest قرار داشته باشد، که در این صورت message/rfc822 خواهد بود. اگر سرآیند Content-Type دارای مشخصه‌ی نوع نامعتبر باشد، RFC 2045 الزام می‌کند که نوع پیش‌فرض text/plain باشد.)

get_content_maintype()

نوع محتوای اصلی پیام را برمی‌گرداند. این، بخش maintype از رشته‌ای است که توسط get_content_type() برگردانده می‌شود.

get_content_subtype()

زیرنوع محتوای پیام را برمی‌گرداند. این مقدار بخش subtype از رشته‌ای است که get_content_type() برمی‌گرداند.

get_default_type()

نوع محتوای پیش‌فرض را برمی‌گرداند. بیشتر پیام‌ها نوع محتوای پیش‌فرض text/plain دارند، به جز پیام‌هایی که زیربخش‌هایی از ظرف‌های multipart/digest هستند. این زیربخش‌ها نوع محتوای پیش‌فرض message/rfc822 دارند.

set_default_type(ctype)

نوع محتوای پیش‌فرض را تنظیم کنید. ctype باید یا text/plain یا message/rfc822 باشد، اگرچه این موضوع اعمال نمی‌شود. نوع محتوای پیش‌فرض در سرآیند Content-Type ذخیره نمی‌شود، بنابراین تنها زمانی بر مقدار بازگشتی متدهای get_content_type تأثیر می‌گذارد که هیچ سرآیند Content-Type در پیام وجود نداشته باشد.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

پارامتری را در سرآیند Content-Type تنظیم می‌کند. اگر پارامتر از قبل در سرآیند وجود داشته باشد، مقدار آن را با value جایگزین می‌کند. هنگامی که header برابر Content-Type (پیش‌فرض) باشد و سرآیند هنوز در پیام وجود نداشته باشد، آن را اضافه می‌کند، مقدار آن را روی text/plain تنظیم می‌کند و مقدار پارامتر جدید را به آن می‌افزاید. header اختیاری، سرآیند جایگزینی را برای Content-Type مشخص می‌کند.

اگر مقدار شامل نویسه‌های غیر ASCII باشد، می‌توان مجموعه نویسه و زبان را با استفاده از پارامترهای اختیاری charset و language به‌صراحت مشخص کرد. پارامتر اختیاری language زبان RFC 2231 را مشخص می‌کند و پیش‌فرض آن رشته خالی است. هر دو پارامتر charset و language باید رشته باشند. پیش‌فرض استفاده از utf8 برای charset و None برای language است.

اگر replace برابر False باشد (پیش‌فرض)، سرآیند به انتهای فهرست سرآیندها منتقل می‌شود. اگر replace برابر True باشد، سرآیند در همان جای خود به‌روزرسانی خواهد شد.

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

توجه داشته باشید که مقادیر پارامترهای موجود در سرآیندها از طریق ویژگی params در مقدار سرآیند قابل دسترسی هستند (برای مثال، msg['Content-Type'].params['charset']).

تغییر یافته در نسخه‌ی 3.4: کلیدواژه‌ی replace اضافه شد.

del_param(param, header='content-type', requote=True)

پارامتر داده‌شده را به‌طور کامل از سرآیند Content-Type حذف کنید. سرآیند به‌صورت درجا بدون پارامتر یا مقدار آن بازنویسی خواهد شد. پارامتر اختیاری header جایگزینی برای Content-Type مشخص می‌کند.

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

get_filename(failobj=None)

مقدار پارامتر filename در سرآیند Content-Disposition پیام را برمی‌گرداند. اگر سرآیند پارامتر filename نداشته باشد، این متد به‌عنوان جایگزین، پارامتر name را در سرآیند Content-Type جست‌وجو می‌کند. اگر هیچ‌کدام پیدا نشود یا سرآیند وجود نداشته باشد، failobj برگردانده می‌شود. رشته برگردانده‌شده همیشه طبق email.utils.unquote() بدون علامت نقل‌قول خواهد بود.

get_boundary(failobj=None)

مقدار پارامتر boundary از سرآیند Content-Type پیام را برمی‌گرداند، یا اگر سرآیند موجود نباشد یا پارامتر boundary نداشته باشد، failobj را برمی‌گرداند. رشته‌ی بازگشتی همیشه مطابق email.utils.unquote() بدون علامت نقل‌قول خواهد بود.

set_boundary(boundary)

پارامتر boundary در سرآیند Content-Type را روی boundary تنظیم کنید. set_boundary() در صورت لزوم همیشه boundary را داخل علامت نقل‌قول قرار می‌دهد. اگر شیء پیام فاقد سرآیند Content-Type باشد، استثنای HeaderParseError پرتاب می‌شود.

توجه داشته باشید که استفاده از این متد به‌صورت ظریفی با حذف سرآیند قدیمی Content-Type و افزودن یک سرآیند جدید با مرز جدید (boundary) از طریق add_header() متفاوت است، زیرا set_boundary() ترتیب سرآیند Content-Type را در فهرست سرآیندها حفظ می‌کند.

get_content_charset(failobj=None)

پارامتر charset سرآیند Content-Type را، پس از تبدیل به حروف کوچک، برمی‌گرداند. اگر سرآیند Content-Type وجود نداشته باشد، یا آن سرآیند پارامتر charset نداشته باشد، failobj برگردانده می‌شود.

get_charsets(failobj=None)

فهرستی شامل نام‌های مجموعه‌نویسه در پیام را برمی‌گرداند. اگر پیام از نوع multipart باشد، فهرست شامل یک المان برای هر زیربخش در بار خواهد بود، در غیر این صورت، فهرستی به طول ۱ خواهد بود.

هر آیتم در فهرست، یک رشته خواهد بود که مقدار پارامتر charset در سرآیند Content-Type برای زیربخش متناظر است. اگر زیربخش سرآیند Content-Type یا پارامتر charset نداشته باشد، یا نوع اصلی MIME آن text نباشد، آن آیتم در فهرست بازگشتی برابر failobj خواهد بود.

is_attachment()

اگر سرآیند Content-Disposition وجود داشته باشد و مقدار آن (بدون حساسیت به بزرگی و کوچکی حروف) attachment باشد، True را برمی‌گرداند و در غیر این صورت False را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.4.2: is_attachment اکنون برای هماهنگی با is_multipart()، به‌جای یک پراپرتی، یک متد است.

get_content_disposition()

اگر پیام سرآیند Content-Disposition داشته باشد، مقدار با حروف کوچک آن (بدون پارامترها) را برمی‌گرداند؛ در غیر این صورت None را برمی‌گرداند. اگر پیام از RFC 2183 پیروی کند، مقادیر ممکن برای این متد inline، attachment یا None هستند.

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

متدهای زیر به بررسی و دستکاری محتوای (payload) پیام مربوط می‌شوند.

walk()

متد walk() یک تولیدگر همه‌منظوره است که می‌توان از آن برای تکرار روی تمام بخش‌ها و زیربخش‌های درخت شیء پیام، به ترتیب پیمایش عمق‌اول استفاده کرد. شما معمولاً از walk() به‌عنوان پیمایش‌گر در یک حلقه for استفاده می‌کنید؛ هر تکرار، زیربخش بعدی را برمی‌گرداند.

در اینجا مثالی آمده که نوع MIME هر بخش از یک ساختار پیام چندبخشی را چاپ می‌کند:

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk زیربخش‌های هر بخشی را که is_multipart() مقدار True برمی‌گرداند، پیمایش می‌کند، هرچند ممکن است msg.get_content_maintype() == 'multipart' مقدار False برگرداند. می‌توانیم این را در مثال خود با استفاده از تابع کمکی اشکال‌زدایی _structure ببینیم:

>>> from email.iterators import _structure
>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain

در اینجا بخش‌های message از نوع multiparts نیستند، اما شامل زیربخش‌هایی هستند. is_multipart() مقدار True را برمی‌گرداند و walk وارد زیربخش‌ها می‌شود.

get_body(preferencelist=('related', 'html', 'plain'))

بخش MIME را که بهترین نامزد برای «بدنه» پیام است، برمی‌گرداند.

preferencelist باید دنباله‌ای از رشته‌هایی از مجموعه related، html و plain باشد و ترتیب اولویت برای نوع محتوای بخش برگردانده‌شده را نشان می‌دهد.

جست‌وجوی تطبیق‌های نامزد را با شیءای که متد get_body روی آن فراخوانی می‌شود، آغاز کنید.

اگر related در preferencelist گنجانده نشده باشد، بخش ریشه (یا زیربخشی از بخش ریشه) هر related که با آن مواجه می‌شوید را در صورتی به‌عنوان نامزد در نظر بگیرید که آن (زیر)بخش با ترجیحی مطابقت داشته باشد.

هنگام مواجهه با multipart/related، پارامتر start را بررسی کنید و اگر بخشی با Content-ID منطبق پیدا شد، هنگام جست‌وجو برای تطابق‌های محتمل فقط آن را در نظر بگیرید. در غیر این صورت فقط بخش نخست (ریشه پیش‌فرض) از multipart/related را در نظر بگیرید.

اگر بخشی سرآیند Content-Disposition داشته باشد، تنها در صورتی آن بخش را یک نامزد تطابق در نظر بگیرید که مقدار سرآیند inline باشد.

اگر هیچ‌یک از نامزدها با هیچ‌یک از ترجیحات موجود در preferencelist مطابقت نداشت، None را برگردانید.

یادداشت‌ها: (۱) برای بیشتر برنامه‌ها، تنها ترکیب‌های preferencelist که واقعاً منطقی هستند، ('plain',)، ('html', 'plain') و پیش‌فرض ('related', 'html', 'plain') هستند. (۲) از آنجا که تطبیق از شیءای آغاز می‌شود که get_body روی آن فراخوانی می‌شود، فراخوانی get_body روی یک multipart/related خود شیء را برمی‌گرداند، مگر اینکه preferencelist مقداری غیر از مقدار پیش‌فرض داشته باشد. (۳) پیام‌ها (یا بخش‌های پیام) که Content-Type را مشخص نمی‌کنند یا سرآیند Content-Type آن‌ها نامعتبر است، به‌عنوان نوع text/plain در نظر گرفته می‌شوند، که ممکن است گاهی باعث شود get_body نتایج غیرمنتظره‌ای برگرداند.

iter_attachments()

پیمایش‌گری بر همه زیربخش‌های مستقیم پیام که بخش‌های نامزد «بدنه» نیستند برمی‌گرداند. یعنی از نخستین رخداد هر یک از text/plain، text/html، multipart/related یا multipart/alternative می‌گذرد (مگر اینکه به‌صراحت از طریق Content-Disposition: attachment به‌عنوان پیوست علامت‌گذاری شده باشند) و همه بخش‌های باقی‌مانده را برمی‌گرداند. هنگامی که مستقیماً بر یک multipart/related اعمال شود، پیمایش‌گری بر همه بخش‌های مرتبط به جز بخش ریشه برمی‌گرداند (یعنی بخشی که پارامتر start به آن اشاره دارد، یا نخستین بخش در صورتی که پارامتر start وجود نداشته باشد یا پارامتر start با Content-ID هیچ‌یک از بخش‌ها مطابقت نداشته باشد). هنگامی که مستقیماً بر یک multipart/alternative یا غیر multipart اعمال شود، یک پیمایش‌گر خالی برمی‌گرداند.

iter_parts()

پیمایش‌گری روی همه‌ی زیربخش‌های مستقیم پیام برمی‌گرداند که برای یک پیام غیر multipart خالی خواهد بود. (همچنین walk() را ببینید.)

get_content(*args, content_manager=None, **kw)

متد get_content() از content_manager را فراخوانی کنید، self را به‌عنوان شیء پیام ارسال کنید، و هر آرگومان یا کلیدواژه دیگر را نیز به‌عنوان آرگومان‌های اضافی همراه آن ارسال کنید. اگر content_manager مشخص نشده باشد، از content_manager مشخص‌شده توسط policy فعلی استفاده کنید.

set_content(*args, content_manager=None, **kw)

متد set_content() از content_manager را فراخوانی کنید و self را به‌عنوان شیء پیام و هر آرگومان یا کلیدواژه دیگر را به‌عنوان آرگومان‌های اضافی ارسال کنید. اگر content_manager مشخص‌نشده باشد، از content_manager تعیین‌شده توسط policy جاری استفاده کنید.

make_related(boundary=None)

یک پیام غیر multipart را به یک پیام multipart/related تبدیل می‌کند و هرگونه سرآیند Content- و بار موجود را به بخش نخست (جدید) از multipart منتقل می‌کند. اگر boundary مشخص شده باشد، از آن به‌عنوان رشته‌ی مرز در multipart استفاده می‌شود؛ در غیر این صورت، مرز به‌صورت خودکار در زمان نیاز ایجاد می‌شود (برای مثال، هنگامی که پیام سریال‌سازی می‌شود).

make_alternative(boundary=None)

یک پیام غیر multipart یا یک multipart/related را به multipart/alternative تبدیل می‌کند و تمام سرآیندهای Content- و بار موجود را به اولین بخش (جدید) از multipart منتقل می‌کند. اگر boundary مشخص شده باشد، از آن به‌عنوان رشته‌ی مرزی در multipart استفاده می‌کند، در غیر این صورت اجازه می‌دهد مرز به‌صورت خودکار در زمانی که به آن نیاز است (برای مثال، هنگامی که پیام سریال‌سازی می‌شود) ایجاد شود.

make_mixed(boundary=None)

یک پیام غیر multipart، یک multipart/related، یا یک multipart-alternative را به یک multipart/mixed تبدیل می‌کند و همه‌ی سرآیندهای Content- و بار موجود را به نخستین بخش (جدید) از multipart منتقل می‌کند. اگر boundary مشخص شده باشد، از آن به‌عنوان رشته‌ی مرز در multipart استفاده می‌شود، در غیر این صورت مرز به‌صورت خودکار در زمان نیاز (برای مثال، هنگامی که پیام سریال‌سازی می‌شود) ایجاد می‌شود.

add_related(*args, content_manager=None, **kw)

اگر پیام یک multipart/related باشد، یک شیء پیام جدید ایجاد کنید، تمام آرگومان‌ها را به متد set_content() آن منتقل کنید و آن را با attach() به multipart پیوست کنید. اگر پیام غیر multipart باشد، make_related() را فراخوانی کنید و سپس مطابق آنچه گفته شد ادامه دهید. اگر پیام هر نوع دیگری از multipart باشد، یک TypeError پرتاب کنید. اگر content_manager مشخص نشده باشد، از content_manager مشخص‌شده توسط policy فعلی استفاده کنید. اگر بخش افزوده‌شده سرآیند Content-Disposition نداشته باشد، سرآیندی با مقدار inline اضافه کنید.

add_alternative(*args, content_manager=None, **kw)

اگر پیام multipart/alternative باشد، یک شیء پیام جدید ایجاد کنید، همه‌ی آرگومان‌ها را به متد set_content() آن ارسال کنید و آن را با attach() به multipart پیوست کنید. اگر پیام غیر multipart یا multipart/related باشد، make_alternative() را فراخوانی کنید و سپس مطابق بالا ادامه دهید. اگر پیام هر نوع دیگری از multipart باشد، یک TypeError پرتاب کنید. اگر content_manager مشخص نشده باشد، از content_manager تعیین‌شده توسط policy فعلی استفاده کنید.

add_attachment(*args, content_manager=None, **kw)

اگر پیام multipart/mixed باشد، یک شیء پیام جدید ایجاد کنید، تمام آرگومان‌ها را به متد set_content() آن ارسال کنید، و آن را به multipart attach() کنید. اگر پیام غیر multipart، multipart/related یا multipart/alternative باشد، make_mixed() را فراخوانی کنید و سپس مطابق بالا ادامه دهید. اگر content_manager مشخص نشده باشد، از content_manager مشخص‌شده توسط policy فعلی استفاده کنید. اگر بخش افزوده‌شده سرآیند Content-Disposition نداشته باشد، سرآیندی با مقدار attachment اضافه کنید. از این متد می‌توان هم برای پیوست‌های صریح (Content-Disposition: attachment) و هم برای پیوست‌های inline (Content-Disposition: inline)، با ارسال گزینه‌های مناسب به content_manager استفاده کرد.

clear()

بار و همه‌ی سرآیندها را حذف کنید.

clear_content()

بار و تمام سرآیندهای !Content- را حذف کنید و تمام سرآیندهای دیگر را دست‌نخورده و با ترتیب اصلی خود باقی بگذارید.

اشیاء EmailMessage دارای ویژگی‌های نمونه زیر هستند:

preamble

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

ویژگی preamble شامل این متن محافظتی اضافی پیشرو برای اسناد MIME است. هنگامی که Parser متنی را پس از سرآیندها اما پیش از اولین رشته‌ی مرزی پیدا کند، آن متن را به ویژگی preamble پیام اختصاص می‌دهد. هنگامی که Generator در حال نوشتن نمایش متنی ساده‌ی یک پیام MIME باشد و ببیند پیام دارای ویژگی preamble است، این متن را در ناحیه‌ی بین سرآیندها و اولین مرز می‌نویسد. برای جزئیات، email.parser و email.generator را ببینید.

توجه داشته باشید که اگر شیء پیام فاقد پیش‌درآمد (preamble) باشد، ویژگی preamble برابر None خواهد بود.

epilogue

ویژگی epilogue همانند ویژگی preamble عمل می‌کند، با این تفاوت که شامل متنی است که بین آخرین مرز و پایان پیام ظاهر می‌شود. همان‌طور که در مورد preamble نیز صدق می‌کند، اگر متن پس‌درآمد وجود نداشته باشد، این ویژگی None خواهد بود.

defects

ویژگی defects شامل فهرستی از تمام مشکلات یافت‌شده هنگام تجزیه این پیام است. برای شرح دقیق نقص‌های ممکن در تجزیه، email.errors را ببینید.

class email.message.MIMEPart(policy=default)

این کلاس نمایانگر یک زیربخش از پیام MIME است. این کلاس با EmailMessage یکسان است، با این تفاوت که هنگام فراخوانی set_content()، هیچ سرآیند MIME-Version اضافه نمی‌شود، زیرا زیربخش‌ها به سرآیندهای MIME-Version خود نیاز ندارند.

پانویس‌ها

[1]

در ابتدا در 3.4 به‌عنوان یک ماژول موقت (provisional module) افزوده شد. مستندات کلاس پیام قدیمی به email.message.Message: بازنمایی یک پیام ایمیل با استفاده از API compat32 منتقل شد.

[2]

کلاس EmailMessage به یک سیاست نیاز دارد که ویژگی content_manager را فراهم کند تا متدهای مدیریت محتوا مانند set_content() و get_content() کار کنند. سیاست قدیمی compat32 این متدها را پشتیبانی نمی‌کند و نباید با EmailMessage استفاده شود.