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 سریالسازی شود.
The email package does its best to hide the details of the various governing RFCs from the application. Conceptually the application should be able to treat the email message as a structured tree of Unicode text and binary attachments, without having to worry about how these are represented when serialized. In practice, however, it is often necessary to be aware of at least some of the rules governing MIME messages and their structure, specifically the names and nature of the MIME "content types" and how they identify multipart documents. For the most part this knowledge should only be required for more complex applications, and even then it should only be the high level structure in question, and not the details of how those structures are represented. Since MIME content types are used widely in modern internet software (not just email), this will be a familiar concept to many programmers.
بخشهای زیر کارکرد بستهی email را توصیف میکنند. ما با مدل شیء message آغاز میکنیم، که رابط اصلیای است که یک برنامه از آن استفاده خواهد کرد، و پس از آن به کامپوننتهای parser و generator میپردازیم. سپس کنترلهای policy را پوشش میدهیم، که بررسی کامپوننتهای اصلی کتابخانه را کامل میکند.
سه بخش بعدی به بررسی استثناهایی میپردازند که این بسته ممکن است پرتاب کند و نقصها (عدم انطباق با RFCها) را که parser ممکن است شناسایی کند. سپس به بررسی کامپوننتهای فرعی headerregistry و contentmanager میپردازیم، که به ترتیب ابزارهایی برای دستکاری جزئیتر سرآیندها و بارهای پیام فراهم میکنند. هر دوی این کامپوننتها دارای ویژگیهایی مرتبط با مصرف و تولید پیامهای غیرساده هستند و همچنین مستندات APIهای توسعهپذیری خود را نیز ارائه میکنند، که برای برنامههای پیشرفته جالب توجه خواهد بود.
پس از آنها، مجموعهای از مثالها برای استفاده از بخشهای بنیادی APIهای پوششدادهشده در بخشهای پیشین آمده است.
The foregoing represent the modern (Unicode friendly) API of the email package.
The remaining sections, starting with the Message
class, cover the legacy compat32 API that deals much more
directly with the details of how email messages are represented. The
compat32 API does not hide the details of the RFCs from
the application, but for applications that need to operate at that level, they
can be useful tools. This documentation is also relevant for applications that
are still using the compat32 API for backward
compatibility reasons.
تغییر یافته در نسخهی 3.6: مستندات برای ترویج API جدید EmailMessage/EmailPolicy بازآرایی و بازنویسی شدند.
محتویات مستندات بستهی email:
API قدیمی:
همچنین ملاحظه نمائید