email.message.Message: بازنمایی یک پیام ایمیل با استفاده از API compat32¶

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

فلسفه و ساختار این دو کلاس، در سایر موارد یکسان است.

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

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

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

شبه‌دیکشنری Message با نام سرآیندها اندیس‌دهی می‌شود، که باید مقادیر ASCII باشند. مقادیر این دیکشنری رشته‌هایی هستند که انتظار می‌رود فقط شامل نویسه‌های ASCII باشند؛ برای ورودی غیر ASCII مدیریت ویژه‌ای وجود دارد، اما این مدیریت همیشه نتایج صحیح را تولید نمی‌کند. سرآیندها با حفظ بزرگی و کوچکی حروف ذخیره و برگردانده می‌شوند، اما نام فیلدها بدون حساسیت به بزرگی و کوچکی حروف تطبیق داده می‌شوند. همچنین ممکن است یک سرآیند پاکت (envelope header) واحد وجود داشته باشد، که به آن سرآیند Unix-From یا سرآیند From_ نیز گفته می‌شود. بار در اشیای پیام ساده، یا یک رشته است یا بایت‌ها، و در اسناد ظرف MIME (مانند multipart/* و message/rfc822) فهرستی از اشیای Message است.

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

class email.message.Message(policy=compat32)¶

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

تغییر یافته در نسخه‌ی 3.3: آرگومان کلیدواژه‌ای policy افزوده شد.

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

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

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

توجه داشته باشید که این متد برای سهولت فراهم شده است و ممکن است همیشه پیام را آن‌گونه که می‌خواهید قالب‌بندی نکند. برای مثال، به‌طور پیش‌فرض، دست‌کاری سطرهایی که با From شروع می‌شوند و قالب mbox یونیکس آن را ایجاب می‌کند انجام نمی‌دهد. برای انعطاف‌پذیری بیشتر، نمونه‌ای از Generator ایجاد کنید و مستقیماً از متد flatten() آن استفاده کنید. برای مثال:

from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

اگر شیء پیام داده‌های دودویی داشته باشد که طبق استانداردهای RFC کدگذاری نشده باشند، داده‌های ناسازگار با نقاط‌کدهای یونیکد «نویسه ناشناس» جایگزین خواهند شد. (همچنین به as_bytes() و BytesGenerator مراجعه کنید.)

تغییر یافته در نسخه‌ی 3.4: آرگومان کلیدواژه‌ای policy افزوده شد.

__str__()¶

معادل as_string(). به str(msg) اجازه می‌دهد رشته‌ای حاوی پیام قالب‌بندی‌شده تولید کند.

as_bytes(unixfrom=False, policy=None)¶

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

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

توجه داشته باشید که این متد برای سهولت ارائه شده است و ممکن است همیشه پیام را به شکلی که می‌خواهید قالب‌بندی نکند. برای مثال، به‌طور پیش‌فرض، دستکاری سطرهایی که با From آغاز می‌شوند و قالب mbox یونیکس به آن نیاز دارد را انجام نمی‌دهد. برای انعطاف‌پذیری بیشتر، یک نمونه از BytesGenerator ایجاد کنید و مستقیماً از متد flatten() آن استفاده کنید. برای مثال:

from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

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

__bytes__()¶

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

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

is_multipart()¶

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

set_unixfrom(unixfrom)¶

سرآیند پاکت پیام را روی unixfrom تنظیم کنید، که باید یک رشته باشد.

get_unixfrom()¶

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

attach(payload)¶

بار داده‌شده (payload) را به بار کنونی اضافه کنید، که باید پیش از فراخوانی None یا فهرستی از اشیای Message باشد. پس از فراخوانی، بار همیشه فهرستی از اشیای Message خواهد بود. اگر می‌خواهید بار را روی یک شیء اسکالر (scalar)، برای مثال یک رشته، تنظیم کنید، در عوض از set_payload() استفاده کنید.

این یک متد قدیمی است. در کلاس EmailMessage، عملکرد آن با set_content() و متدهای مرتبط make و add جایگزین شده است.

get_payload(i=None, decode=False)¶

بار فعلی را بازمی‌گرداند، که هنگامی که is_multipart() برابر True باشد، فهرستی از اشیاء Message خواهد بود، یا هنگامی که is_multipart() برابر False باشد، یک رشته خواهد بود. اگر بار یک فهرست باشد و شما شیء فهرست را تغییر دهید، بار پیام را درجا تغییر می‌دهید.

با آرگومان اختیاری i، اگر is_multipart() برابر True باشد، get_payload() عنصر i*ام بار را، با شمارش از صفر، برمی‌گرداند. اگر *i کمتر از ۰ یا بزرگ‌تر یا مساوی تعداد آیتم‌های بار باشد، IndexError پرتاب می‌شود. اگر بار یک رشته باشد (یعنی is_multipart() برابر False باشد) و i داده شده باشد، TypeError پرتاب می‌شود.

decode اختیاری پرچمی است که نشان می‌دهد بار باید بر اساس سرآیند Content-Transfer-Encoding کدگشایی شود یا خیر. هنگامی که True باشد و پیام چندبخشی نباشد، اگر مقدار این سرآیند quoted-printable یا base64 باشد، بار کدگشایی خواهد شد. اگر از کدگذاری دیگری استفاده شده باشد یا سرآیند Content-Transfer-Encoding وجود نداشته باشد، بار به‌همان‌صورت (کدگشایی‌نشده) برگردانده می‌شود. در همه حالت‌ها، مقدار برگردانده‌شده داده‌های دودویی است. اگر پیام چندبخشی باشد و پرچم decode True باشد، None برگردانده می‌شود. اگر بار base64 باشد و به‌طور کامل درست تشکیل نشده باشد (نبود پدینگ، نویسه‌های خارج از الفبای base64)، نقص مناسبی به ویژگی نقص پیام افزوده خواهد شد (InvalidBase64PaddingDefect یا InvalidBase64CharactersDefect، به‌ترتیب).

هنگامی که decode برابر False باشد (پیش‌فرض)، بدنه به‌صورت یک رشته بدون کدگشایی بر اساس Content-Transfer-Encoding بازگردانده می‌شود. با این حال، برای Content-Transfer-Encoding با مقدار 8bit، تلاشی برای کدگشایی بایت‌های اصلی با استفاده از charset مشخص‌شده توسط سرآیند Content-Type و با کنترل‌کننده‌ی خطای replace صورت می‌گیرد. اگر هیچ charset مشخص نشده باشد، یا charset داده‌شده توسط بسته‌ی email شناخته نشود، بدنه با استفاده از نویسه‌گان پیش‌فرض ASCII کدگشایی می‌شود.

این یک متد قدیمی است. در کلاس EmailMessage، عملکرد آن با get_content() و iter_parts() جایگزین شده است.

set_payload(payload, charset=None)¶

کل بار شیء پیام را روی payload تنظیم کنید. مسئولیت اطمینان از برقراری ناورداهای بار بر عهده کلاینت است. charset اختیاری، مجموعه‌ی نویسه‌ی پیش‌فرض پیام را تنظیم می‌کند؛ برای جزئیات set_charset() را ببینید.

این یک متد قدیمی است. در کلاس EmailMessage، عملکرد آن با set_content() جایگزین شده است.

set_charset(charset)¶

مجموعه‌ی نویسه‌های بار را روی charset تنظیم کنید، که می‌تواند یک نمونه از Charset (به email.charset مراجعه کنید)، رشته‌ای که نام یک مجموعه نویسه را مشخص می‌کند، یا None باشد. اگر یک رشته باشد، به یک نمونه از Charset تبدیل خواهد شد. اگر charset برابر None باشد، پارامتر charset از سرآیند Content-Type حذف خواهد شد (پیام به‌جز این مورد تغییر دیگری نخواهد کرد). هر چیز دیگری باعث ایجاد TypeError خواهد شد.

اگر سرآیند MIME-Version از قبل وجود نداشته باشد، یکی افزوده می‌شود. اگر سرآیند Content-Type از قبل وجود نداشته باشد، یکی با مقدار text/plain افزوده می‌شود. چه سرآیند Content-Type از قبل وجود داشته باشد و چه نداشته باشد، پارامتر charset آن به charset.output_charset تنظیم می‌شود. اگر charset.input_charset و charset.output_charset متفاوت باشند، بار به output_charset دوباره کدگذاری می‌شود. اگر سرآیند Content-Transfer-Encoding از قبل وجود نداشته باشد، در صورت نیاز، بار با استفاده از Charset تعیین‌شده، کدگذاری انتقالی می‌شود و سرآیندی با مقدار مناسب افزوده می‌شود. اگر سرآیند Content-Transfer-Encoding از قبل وجود داشته باشد، فرض می‌شود بار از قبل به‌درستی با استفاده از همان Content-Transfer-Encoding کدگذاری شده است و تغییر داده نمی‌شود.

این یک متد قدیمی است. در کلاس EmailMessage، عملکرد آن با پارامتر charset متد email.message.EmailMessage.set_content() جایگزین شده است.

get_charset()¶

نمونه‌ی Charset مرتبط با بار پیام را برمی‌گرداند.

این یک متد قدیمی است. در کلاس EmailMessage همیشه None را برمی‌گرداند.

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

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

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

در مدلی که از بایت‌ها تولید شده است، هر یک از مقادیر سرآیند که (برخلاف RFCها) حاوی بایت‌های غیرASCII باشند، هنگام بازیابی از طریق این رابط، به‌صورت اشیای Header با مجموعه‌نویسه‌ی unknown-8bit نمایش داده می‌شوند.

__len__()¶

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

__contains__(name)¶

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

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

__getitem__(name)¶

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

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

__setitem__(name, val)¶

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

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

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

__delitem__(name)¶

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

keys()¶

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

values()¶

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

items()¶

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

get(name, failobj=None)¶

مقدار فیلد سرآیند با نام مشخص‌شده را برمی‌گرداند. این دقیقاً مانند __getitem__() است، با این تفاوت که اگر سرآیند با نام مشخص‌شده وجود نداشته باشد، 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'))

که تولید می‌کند

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)¶

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

get_content_type()¶

نوع محتوای پیام را بازمی‌گرداند. رشته‌ی بازگردانده‌شده به حروف کوچک تبدیل می‌شود و در قالب maintype/subtype خواهد بود. اگر سرآیند Content-Type در پیام وجود نداشته باشد، نوع پیش‌فرض داده‌شده توسط get_default_type() بازگردانده خواهد شد. از آنجا که طبق 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_params(failobj=None, header='content-type', unquote=True)¶

پارامترهای Content-Type پیام را به‌صورت یک فهرست بازمی‌گرداند. عناصر فهرست برگردانده‌شده تاپل‌های دوتایی از جفت‌های کلید/مقدار هستند که بر اساس علامت '=' تفکیک شده‌اند. سمت چپ علامت '=' کلید است، در حالی که سمت راست آن مقدار است. اگر علامت '=' در پارامتر وجود نداشته باشد، مقدار یک رشته خالی است؛ در غیر این صورت مقدار همان‌گونه است که در get_param() توضیح داده شده است و اگر پارامتر اختیاری unquote برابر True باشد (پیش‌فرض)، بدون علامت نقل‌قول می‌شود.

failobj اختیاری، شیءای است که اگر سرآیند Content-Type وجود نداشته باشد، بازگردانده می‌شود. header اختیاری، سرآیندی است که به‌جای Content-Type جستجو می‌شود.

این یک متد قدیمی است. در کلاس EmailMessage، عملکرد آن با ویژگی params اشیای سرآیند جداگانه‌ای که توسط متدهای دسترسی به سرآیند برگردانده می‌شوند، جایگزین شده است.

get_param(param, failobj=None, header='content-type', unquote=True)¶

مقدار پارامتر param از سرآیند Content-Type را به‌صورت یک رشته برمی‌گرداند. اگر پیام سرآیند Content-Type نداشته باشد یا چنین پارامتری وجود نداشته باشد، failobj برگردانده می‌شود (پیش‌فرض آن None است).

header اختیاری، در صورت داده شدن، سرآیند پیامی را مشخص می‌کند که به‌جای Content-Type استفاده می‌شود.

کلیدهای پارامتر همیشه بدون حساسیت به بزرگی و کوچکی حروف مقایسه می‌شوند. مقدار بازگشتی می‌تواند یک رشته باشد، یا یک تاپل سه‌تایی در صورتی که پارامتر مطابق RFC 2231 کدگذاری شده باشد. هنگامی که یک تاپل سه‌تایی باشد، عناصر مقدار به شکل (CHARSET, LANGUAGE, VALUE) هستند. توجه داشته باشید که هر دو CHARSET و LANGUAGE می‌توانند None باشند، که در این صورت باید فرض کنید VALUE با مجموعه‌نویسه us-ascii کدگذاری شده است. معمولاً می‌توانید LANGUAGE را نادیده بگیرید.

اگر برای برنامه‌ی شما اهمیتی ندارد که پارامتر مطابق RFC 2231 کدگذاری شده باشد، می‌توانید با فراخوانی email.utils.collapse_rfc2231_value() و ارسال مقدار بازگشتی از get_param()، مقدار پارامتر را یکپارچه کنید. این تابع، هنگامی که مقدار یک تاپل باشد، یک رشته‌ی Unicode را که به‌طور مناسب کدگشایی شده است برمی‌گرداند، یا در غیر این صورت رشته‌ی اصلی بدون علامت نقل‌قول را برمی‌گرداند. برای مثال:

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

در هر صورت، مقدار پارامتر (چه رشته‌ی برگردانده‌شده، چه آیتم VALUE در ۳-تایی) همیشه بدون علامت نقل‌قول است، مگر اینکه unquote روی False تنظیم شده باشد.

این یک متد قدیمی است. در کلاس EmailMessage، عملکرد آن با ویژگی params اشیای سرآیند جداگانه‌ای که توسط متدهای دسترسی به سرآیند برگردانده می‌شوند، جایگزین شده است.

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

پارامتری را در سرآیند Content-Type تنظیم کنید. اگر پارامتر از قبل در سرآیند وجود داشته باشد، مقدار آن با value جایگزین خواهد شد. اگر سرآیند Content-Type هنوز برای این پیام تعریف‌نشده باشد، به text/plain تنظیم خواهد شد و مقدار پارامتر جدید مطابق RFC 2045 افزوده خواهد شد.

header اختیاری یک سرآیند جایگزین به‌جای Content-Type مشخص می‌کند، و همه‌ی پارامترها در صورت لزوم داخل علامت نقل‌قول قرار می‌گیرند، مگر آنکه requote اختیاری False باشد (پیش‌فرض True است).

اگر charset اختیاری مشخص شده باشد، پارامتر مطابق RFC 2231 کدگذاری خواهد شد. language اختیاری، زبان RFC 2231 را مشخص می‌کند و مقدار پیش‌فرض آن رشته خالی است. هر دو charset و language باید رشته باشند.

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

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

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

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

set_type(type, header='Content-Type', requote=True)¶

نوع اصلی و نوع فرعی را برای سرآیند Content-Type تنظیم کنید. type باید رشته‌ای به شکل maintype/subtype باشد، در غیر این صورت یک ValueError پرتاب می‌شود.

این متد سرآیند Content-Type را جایگزین می‌کند و تمام پارامترها را در جای خود نگه می‌دارد. اگر requote برابر False باشد، نقل‌قول سرآیند موجود همان‌طور که هست باقی می‌ماند، در غیر این صورت پارامترها داخل علامت نقل‌قول قرار می‌گیرند (حالت پیش‌فرض).

می‌توان یک سرآیند جایگزین را در آرگومان header مشخص کرد. هنگامی که سرآیند Content-Type تنظیم شود، سرآیند MIME-Version نیز اضافه می‌شود.

این یک متد قدیمی است. در کلاس EmailMessage، عملکرد آن با متدهای make_ و add_ جایگزین شده است.

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 را در فهرست سرآیندها حفظ می‌کند. با این حال، این کار هیچ‌یک از سطرهای ادامه‌ای را که ممکن است در سرآیند اصلی Content-Type وجود داشته باشد، حفظ نمی‌کند.

get_content_charset(failobj=None)¶

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

توجه داشته باشید که این متد با get_charset() متفاوت است، که نمونه‌ی Charset را برای کدگذاری پیش‌فرض بدنه‌ی پیام برمی‌گرداند.

get_charsets(failobj=None)¶

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

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

get_content_disposition()¶

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

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

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 ببینیم:

>>> 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 وارد زیربخش‌ها می‌شود.

اشیای Message همچنین می‌توانند به‌صورت اختیاری دارای دو ویژگی نمونه باشند، که می‌توان از آن‌ها هنگام تولید متن ساده یک پیام MIME استفاده کرد.

preamble¶

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

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

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

epilogue¶

ویژگی epilogue مانند ویژگی preamble عمل می‌کند، با این تفاوت که شامل متنی است که میان آخرین مرز (boundary) و پایان پیام قرار می‌گیرد.

برای اینکه Generator یک خط جدید در پایان پرونده چاپ کند، نیازی نیست بخش پایانی (epilogue) را به رشته خالی تنظیم کنید.

defects¶

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