email --- بستهای برای مدیریت ایمیل و MIME¶
کد منبع: Lib/email/__init__.py
بستهی email کتابخانهای برای مدیریت پیامهای ایمیل است. این بسته بهطور مشخص برای ارسال هیچگونه پیام ایمیل به SMTP (RFC 2821)، NNTP یا سایر سرورها طراحی نشده است؛ این موارد، کارکردهای ماژولهایی مانند smtplib هستند. بستهی email تلاش میکند تا حد امکان با RFCها منطبق باشد و از RFC 5322 و RFC 6532 و همچنین RFCهای مرتبط با MIME مانند RFC 2045، RFC 2046، RFC 2047، RFC 2183 و RFC 2231 پشتیبانی میکند.
ساختار کلی بسته email را میتوان به سه کامپوننت اصلی تقسیم کرد، بهعلاوه یک کامپوننت چهارم که رفتار سایر کامپوننتها را کنترل میکند.
کامپوننت مرکزی بسته، یک «مدل شیء» است که پیامهای ایمیل را بازنمایی میکند. برنامه عمدتاً از طریق رابط مدل شیء که در زیرماژول message تعریفشده است، با بسته تعامل میکند. برنامه میتواند از این API برای پرسش درباره یک ایمیل موجود، ساخت یک ایمیل جدید، یا افزودن یا حذف زیرکامپوننتهای ایمیل که خود از همان رابط مدل شیء استفاده میکنند، استفاده کند. یعنی، با توجه به ماهیت پیامهای ایمیل و زیرکامپوننتهای MIME آنها، مدل شیء ایمیل ساختاری درختی از اشیاء است که همگی API EmailMessage را فراهم میکنند.
دو کامپوننت اصلی دیگر بسته، parser و generator هستند. پارسر نسخهی سریالشدهی یک پیام ایمیل (جریانی از بایتها) را میگیرد و آن را به درختی از اشیای EmailMessage تبدیل میکند. تولیدگر یک EmailMessage را میگیرد و آن را دوباره به یک جریان بایت سریالشده تبدیل میکند. (پارسر و تولیدگر جریانهایی از نویسههای متنی را نیز مدیریت میکنند، اما این کاربرد توصیه نمیشود، زیرا بسیار آسان است که در نهایت به پیامهایی برسید که به نحوی نامعتبر هستند.)
کامپوننت کنترلی، ماژول policy است. هر EmailMessage، هر generator و هر parser یک شیء policy مرتبط دارد که رفتار آن را کنترل میکند. معمولاً یک برنامه فقط نیاز دارد سیاست را هنگام ایجاد یک EmailMessage مشخص کند؛ چه با نمونهسازی مستقیم یک EmailMessage برای ایجاد یک ایمیل جدید، چه با تجزیه یک جریان ورودی با استفاده از parser. اما میتوان سیاست را هنگام سریالسازی پیام با استفاده از generator تغییر داد. این امکان را فراهم میکند که برای مثال یک پیام ایمیل عام از دیسک تجزیه شود، اما هنگام ارسال آن به یک سرور ایمیل، با استفاده از تنظیمات استاندارد SMTP سریالسازی شود.
بسته email حداکثر تلاش خود را میکند تا جزئیات RFCهای مختلف حاکم را از برنامه پنهان نگه دارد. از نظر مفهومی، برنامه باید بتواند پیام ایمیل را به عنوان یک درخت ساختاریافته از متن یونیکد و پیوستهای دودویی در نظر بگیرد، بدون نیاز به نگرانی درباره نحوه نمایش آنها هنگام سریالسازی. در عمل، با این حال، اغلب لازم است که از حداقل برخی از قوانین حاکم بر پیامهای MIME و ساختار آنها آگاه باشید، بهویژه نامها و ماهیت «نوعهای محتوا» MIME و نحوه شناسایی اسناد چندبخشی توسط آنها. برای اکثر بخشها، این دانش تنها برای برنامههای پیچیدهتر مورد نیاز است، و حتی در آن صورت نیز تنها باید ساختار سطح بالا مورد پرسش باشد، نه جزئیات نحوه نمایش آن ساختارها. از آنجا که نوعهای محتوای MIME به طور گسترده در نرمافزارهای اینترنتی مدرن (نه تنها ایمیل) استفاده میشوند، این مفهوم برای بسیاری از برنامهنویسان آشنا خواهد بود.
بخشهای زیر کارکرد بستهی email را توصیف میکنند. ما با مدل شیء message آغاز میکنیم، که رابط اصلیای است که یک برنامه از آن استفاده خواهد کرد، و پس از آن به کامپوننتهای parser و generator میپردازیم. سپس کنترلهای policy را پوشش میدهیم، که بررسی کامپوننتهای اصلی کتابخانه را کامل میکند.
سه بخش بعدی به بررسی استثناهایی میپردازند که این بسته ممکن است پرتاب کند و نقصها (عدم انطباق با RFCها) را که parser ممکن است شناسایی کند. سپس به بررسی کامپوننتهای فرعی headerregistry و contentmanager میپردازیم، که به ترتیب ابزارهایی برای دستکاری جزئیتر سرآیندها و بارهای پیام فراهم میکنند. هر دوی این کامپوننتها دارای ویژگیهایی مرتبط با مصرف و تولید پیامهای غیرساده هستند و همچنین مستندات APIهای توسعهپذیری خود را نیز ارائه میکنند، که برای برنامههای پیشرفته جالب توجه خواهد بود.
پس از آنها، مجموعهای از مثالها برای استفاده از بخشهای بنیادی APIهای پوششدادهشده در بخشهای پیشین آمده است.
مقدمههای فوق APIهای مدرن (دوستدار یونیکد) بسته email را نشان میدهند. بخشهای باقیمانده، با شروع از کلاس Message، API قدیمی compat32 را پوشش میدهند که مستقیماًتر با جزئیات نحوه نمایش پیامهای ایمیل سروکار دارد. API compat32 جزئیات RFCها را از برنامه پنهان نمیکند، اما برای برنامههایی که نیاز به کار در آن سطح دارند، میتوانند ابزارهای مفیدی باشند. این مستندات همچنین برای برنامههایی که همچنان از API compat32 به دلایل سازگاری عقبگرد استفاده میکنند، مرتبط است.
تغییر یافته در نسخهی 3.6: مستندات برای ترویج API جدید EmailMessage/EmailPolicy بازآرایی و بازنویسی شدند.
محتویات مستندات بستهی email:
API قدیمی:
همچنین ملاحظه نمائید