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

این مدیر محتوا تنها یک رابط حداقل فراتر از آنچه توسط خود Message فراهم شده است، ارائه می‌دهد: آن تنها با متن، بایت‌های خام، و اشیاء Message سروکار دارد. با این حال، مزایای قابل‌توجهی در مقایسه با API پایه فراهم می‌کند: get_content در یک بخش متنی یک رشته برمی‌گرداند بدون اینکه برنامه نیاز به کدگشایی دستی آن داشته باشد، set_content یک مجموعه غنی از گزینه‌ها برای کنترل سرآیندهای اضافه شده به یک بخش و کنترل کدگذاری انتقال محتوا فراهم می‌کند، و امکان استفاده از متدهای مختلف add_ را فراهم می‌کند، که در نتیجه ایجاد پیام‌های چندبخشی را ساده می‌کند.

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

بار بخش را به صورت یک رشته (برای بخش‌های text)، یک شیء EmailMessage (برای بخش‌های message/rfc822)، یا یک شیء bytes (برای تمام انواع غیر-چندبخشی دیگر) برگردانید. اگر روی یک multipart فراخوانی شود، KeyError به وجود آورید. اگر بخش یک بخش text باشد و errors مشخص شده باشد، از آن به عنوان هندلر خطا هنگام کدگشایی بار به یک رشته استفاده کنید. هندلر خطای پیش‌فرض 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 اضافه می‌شوند.

پانویس‌ها