نمونه‌های مدیر محتوا (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 اضافه می‌شوند.

پانویس‌ها