email.contentmanager: مدیریت محتوای MIME

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

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

class email.contentmanager.ContentManager

کلاس پایه برای مدیران محتوا. سازوکارهای استاندارد ثبت برای ثبت مبدل‌ها میان محتوای MIME و سایر نمایش‌ها، و همچنین متدهای اعزام (dispatch) get_content و set_content را فراهم می‌کند.

get_content(msg, *args, **kw)

یک تابع هندلر را بر اساس mimetype مربوط به msg پیدا کنید (پاراگراف بعدی را ببینید)، آن را با ارسال همه‌ی آرگومان‌ها فراخوانی کنید و نتیجه‌ی فراخوانی را برگردانید. انتظار می‌رود که کنترل‌گر بار را از msg استخراج کند و شیءای را برگرداند که اطلاعاتی درباره‌ی داده‌ی استخراج‌شده را کدگذاری می‌کند.

برای یافتن هندلر، کلیدهای زیر را در رجیستری جستجو کنید و با پیدا شدن اولین مورد، متوقف شوید:

  • رشته‌ای که نوع کامل MIME را نشان می‌دهد (maintype/subtype)

  • رشته‌ی نشان‌دهنده‌ی maintype

  • رشته خالی

اگر هیچ‌کدام از این کلیدها یک هندلر ایجاد نکردند، برای نوع کامل MIME یک KeyError پرتاب کنید.

set_content(msg, obj, *args, **kw)

اگر maintype برابر با multipart باشد، استثنای TypeError پرتاب می‌شود؛ در غیر این صورت، یک تابع هندلر بر اساس نوع obj جستجو می‌شود (بند بعدی را ببینید)، clear_content() روی msg فراخوانی می‌شود و تابع هندلر با ارسال تمام آرگومان‌ها فراخوانی می‌شود. انتظار می‌رود که هندلر obj را تبدیل کرده و در msg ذخیره کند، و احتمالاً تغییرات دیگری نیز در msg اعمال کند، مانند افزودن سرآیندهای MIME مختلف برای کدگذاری اطلاعات لازم برای تفسیر داده‌ی ذخیره‌شده.

برای یافتن هندلر، نوع obj را به دست آورید (typ = type(obj)) و در رجیستری به دنبال کلیدهای زیر بگردید و با نخستین کلید یافت‌شده متوقف شوید:

  • خودِ نوع (typ)

  • نام کامل مشخص نوع (typ.__module__ + '.' + typ.__qualname__).

  • qualname نوع (typ.__qualname__)

  • nameنوع (typ.__name__).

اگر هیچ‌یک از موارد بالا مطابقت نداشت، تمام بررسی‌های بالا را برای هر یک از انواع موجود در MRO (typ.__mro__) تکرار کنید. در نهایت، اگر هیچ کلید دیگری هندلری را برنگرداند، بررسی کنید که آیا مدیری برای کلید None وجود دارد. اگر هندلری برای None وجود نداشت، KeyError را برای نام کامل نوع پرتاب کنید.

همچنین اگر سرآیند MIME-Version وجود ندارد، آن را اضافه کنید (همچنین MIMEPart را ببینید).

add_get_handler(key, handler)

تابع handler را به‌عنوان هندلر برای key ثبت کنید. برای مقادیر ممکن key، get_content() را ببینید.

add_set_handler(typekey, handler)

handler را به‌عنوان تابعی ثبت کنید که هنگام ارسال شیءای از نوع مطابق با typekey به set_content() فراخوانی می‌شود. برای مقادیر ممکن typekey، set_content() را ببینید.

نمونه‌های مدیر محتوا (Content Manager)

در حال حاضر بسته‌ی email تنها یک مدیر محتوای عینی (concrete content manager)، raw_data_manager، ارائه می‌دهد، هرچند ممکن است در آینده موارد بیشتری افزوده شوند. raw_data_manager همان content_manager ارائه‌شده از سوی EmailPolicy و مشتقات آن است.

email.contentmanager.raw_data_manager

This content manager provides only a minimum interface beyond that provided by Message itself: it deals only with text, raw bytes, and Message objects. Nevertheless, it provides significant advantages compared to the base API: get_content on a text part will return a string without the application needing to manually decode it, set_content provides a rich set of options for controlling the headers added to a part and controlling the content transfer encoding, and it enables the use of the various add_ methods, thereby simplifying the creation of multipart messages.

email.contentmanager.get_content(msg, errors='replace')

Return the payload of the part as either a string (for text parts), an EmailMessage object (for message/rfc822 parts), or a bytes object (for all other non-multipart types). Raise a KeyError if called on a multipart. If the part is a text part and errors is specified, use it as the error handler when decoding the payload to a string. The default error handler is replace.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

سرآیند‌ها و بار را به msg اضافه کنید:

یک سرآیند Content-Type با مقدار maintype/subtype اضافه کنید.

  • برای str، maintype MIME را روی text تنظیم کنید، و زیرنوع را اگر مشخص شده باشد روی subtype و در غیر این صورت روی plain تنظیم کنید.

  • برای bytes، از maintype و subtype مشخص‌شده استفاده می‌شود، یا اگر مشخص نشده باشند، استثنای TypeError پرتاب می‌شود.

  • برای اشیای EmailMessage، نوع اصلی (maintype) روی message تنظیم می‌شود، و اگر subtype مشخص شده باشد، زیرنوع روی subtype و در غیر این صورت روی rfc822 تنظیم می‌شود. اگر subtype برابر partial باشد، خطایی پرتاب می‌شود (برای ساخت بخش‌های message/partial باید از اشیای bytes استفاده شود).

اگر charset ارائه شده باشد (که فقط برای str معتبر است)، رشته با استفاده از مجموعه نویسه مشخص‌شده به بایت‌ها کدگذاری می‌شود. مقدار پیش‌فرض utf-8 است. اگر charset مشخص‌شده نام مستعار شناخته‌شده‌ای برای یک نام مجموعه نویسه استاندارد MIME باشد، به‌جای آن از مجموعه نویسه استاندارد استفاده می‌شود.

اگر cte تنظیم‌شده باشد، بار با استفاده از کدگذاری انتقال محتوای مشخص‌شده کدگذاری می‌شود و سرآیند Content-Transfer-Encoding روی آن مقدار تنظیم می‌شود. مقادیر ممکن برای cte عبارت‌اند از quoted-printable، base64، 7bit، 8bit و binary. اگر ورودی نتواند با کدگذاری مشخص‌شده کدگذاری شود (برای مثال، مشخص کردن cte با مقدار 7bit برای ورودی‌ای که حاوی مقادیر غیر ASCII است)، یک ValueError پرتاب می‌شود.

  • برای اشیاء str، اگر cte تنظیم‌نشده باشد، از روش‌های اکتشافی برای تعیین فشرده‌ترین کدگذاری استفاده می‌شود. پیش از کدگذاری، str.splitlines() برای عادی‌سازی تمام مرزهای سطر استفاده می‌شود تا اطمینان حاصل شود که هر خط از بار با ویژگی linesep سیاست جاری پایان می‌یابد (حتی اگر رشته اصلی با آن پایان‌نیافته باشد).

  • برای اشیاء bytes، اگر cte تنظیم نشده باشد، مقدار آن base64 در نظر گرفته می‌شود و ترجمه‌ی خط جدید مذکور انجام نمی‌شود.

  • برای EmailMessage، بر اساس RFC 2046، اگر برای subtype rfc822، cte برابر quoted-printable یا base64 درخواست شود، یا برای subtype external-body هر cte غیر از 7bit درخواست شود، خطایی پرتاب می‌کند. برای message/rfc822، اگر cte مشخص نشده باشد، از 8bit استفاده می‌شود. برای تمام مقدارهای دیگر subtype، از 7bit استفاده می‌شود.

توجه

یک cte از binary هنوز واقعاً به‌درستی کار نمی‌کند. شیء EmailMessage که با set_content تغییر یافته است، صحیح است، اما BytesGenerator آن را به‌درستی سریال‌سازی نمی‌کند.

اگر disposition تنظیم شده باشد، از آن به‌عنوان مقدار سرآیند Content-Disposition استفاده می‌شود. اگر مشخص نشده باشد و filename مشخص شده باشد، سرآیند با مقدار attachment افزوده می‌شود. اگر disposition مشخص نشده باشد و filename نیز مشخص نشده باشد، سرآیند افزوده نمی‌شود. تنها مقادیر معتبر برای disposition، attachment و inline هستند.

اگر filename تعیین شده باشد، از آن به‌عنوان مقدار پارامتر filename در سرآیند Content-Disposition استفاده کنید.

اگر cid مشخص شده باشد، یک سرآیند Content-ID با cid به‌عنوان مقدار آن اضافه می‌شود.

اگر params تعیین شده باشد، متد items آن را پیمایش کنید و از جفت‌های (key, value) حاصل برای تنظیم پارامترهای اضافی در سرآیند Content-Type استفاده کنید.

اگر headers مشخص شده باشد و فهرستی از رشته‌هایی به‌صورت headername: headervalue یا فهرستی از اشیای header باشد (که با داشتن ویژگی name از رشته‌ها متمایز می‌شوند)، سرآیندها به msg اضافه می‌شوند.

پانویس‌ها