email.mime: ایجاد اشیای ایمیل و MIME از پایه

کد منبع: Lib/email/mime/

---

این ماژول بخشی از API قدیمی ایمیل (Compat32) است. عملکرد آن تا حدی توسط contentmanager در API جدید جایگزین شده است، اما در برخی کاربردها ممکن است این کلاس‌ها هنوز مفید باشند، حتی در کد غیرقدیمی.

به‌طور معمول، شما با ارسال یک پرونده یا مقداری متن به یک پارسر، ساختاری از اشیاء پیام را دریافت می‌کنید؛ این پارسر متن را تجزیه می‌کند و شیء پیام ریشه‌ای را بازمی‌گرداند. با این حال، می‌توانید یک ساختار کامل پیام را از صفر بسازید، یا حتی اشیاء منفرد Message را به‌صورت دستی بسازید. در واقع، می‌توانید یک ساختار موجود را بردارید و اشیاء جدید Message را به آن اضافه کنید، آن‌ها را جابه‌جا کنید و غیره. این امر رابط بسیار مناسبی را برای اسلایس و خرد کردن پیام‌های MIME فراهم می‌کند.

شما می‌توانید با ایجاد نمونه‌های Message، افزودن پیوست‌ها و همه سرآیندهای مناسب به‌صورت دستی، یک ساختار شیء جدید بسازید. البته برای پیام‌های MIME، بسته email چند زیرکلاس مناسب ارائه می‌دهد تا کارها آسان‌تر شود.

کلاس‌ها به شرح زیر هستند:

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

ماژول: email.mime.base

این کلاس پایه برای همه زیرکلاس‌های مختص MIMEِ Message است. معمولاً شما نمونه‌هایی را به‌طور خاص از MIMEBase ایجاد نمی‌کنید، هرچند می‌توانید این کار را بکنید. MIMEBase عمدتاً به‌عنوان یک کلاس پایه مناسب برای زیرکلاس‌های خاص‌ترِ آگاه از MIME ارائه شده است.

_maintype نوع اصلی Content-Type است (برای مثال text یا image)، و _subtype نوع فرعی Content-Type است (برای مثال plain یا gif). _params یک دیکشنری کلید/مقدار پارامترها است و مستقیماً به Message.add_header ارسال می‌شود.

اگر policy مشخص شده باشد، (پیش‌فرض آن سیاست compat32 است) به Message ارسال می‌شود.

کلاس MIMEBase همیشه یک سرآیند Content-Type (بر اساس _maintype، _subtype و _params) و یک سرآیند MIME-Version (که همیشه بر روی 1.0 تنظیم شده است) اضافه می‌کند.

تغییر یافته در نسخه‌ی 3.6: پارامتر فقط کلیدواژه‌ای policy اضافه شد.

class email.mime.nonmultipart.MIMENonMultipart

ماژول: email.mime.nonmultipart

این کلاس، زیرکلاسی از MIMEBase و یک کلاس پایه میانی برای پیام‌های MIME است که multipart نیستند. هدف اصلی این کلاس، جلوگیری از استفاده از متد attach() است که فقط برای پیام‌های multipart معنا دارد. اگر attach() فراخوانی شود، استثنای MultipartConversionError پرتاب می‌شود.

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

ماژول: email.mime.multipart

این کلاس، زیرکلاسی از MIMEBase و کلاس پایه‌ای میانی برای پیام‌های MIME از نوع multipart است. _subtype اختیاری به‌طور پیش‌فرض mixed است، اما می‌توان از آن برای مشخص کردن زیرنوع پیام استفاده کرد. یک سرآیند Content-Type با multipart/_subtype به شیء پیام افزوده خواهد شد. سرآیند MIME-Version نیز افزوده خواهد شد.

boundary اختیاری، رشته‌ی مرز چندبخشی است. هنگامی که None باشد (پیش‌فرض)، مرز در زمان نیاز محاسبه می‌شود (برای مثال، هنگامی که پیام سریال‌سازی می‌شود).

_subparts دنباله‌ای از زیربخش‌های اولیه برای بار است. باید بتوان این دنباله را به یک فهرست تبدیل کرد. شما همیشه می‌توانید با استفاده از متد Message.attach، زیربخش‌های جدیدی را به پیام پیوست کنید.

آرگومان اختیاری policy به‌طور پیش‌فرض compat32 است.

پارامترهای اضافی برای سرآیند Content-Type از آرگومان‌های کلیدواژه‌ای دریافت می‌شوند، یا به آرگومان _params که یک دیکشنری کلیدواژه‌ای است، ارسال می‌شوند.

تغییر یافته در نسخه‌ی 3.6: پارامتر فقط کلیدواژه‌ای policy اضافه شد.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

ماژول: email.mime.application

کلاس MIMEApplication یک زیرکلاس از MIMENonMultipart است و برای بازنمایی اشیاء پیام MIME از نوع اصلی application استفاده می‌شود. _data حاوی بایت‌های داده‌های خام application است. _subtype اختیاری، زیرنوع MIME را مشخص می‌کند و پیش‌فرض آن octet-stream است.

_encoder اختیاری یک فراخوانی‌پذیر، یعنی یک تابع، است که کدگذاری واقعی داده‌ها برای انتقال را انجام می‌دهد. این فراخوانی‌پذیر یک آرگومان می‌گیرد که یک نمونه از MIMEApplication است. این فراخوانی‌پذیر باید از get_payload() و set_payload() استفاده کند تا بار را به صورت کدگذاری‌شده تغییر دهد. همچنین باید در صورت لزوم، سرآیند Content-Transfer-Encoding یا هر سرآیند دیگری را به شیء پیام اضافه کند. کدگذاری پیش‌فرض base64 است. برای مشاهده فهرستی از کدگذارهای توکار، ماژول email.encoders را ببینید.

آرگومان اختیاری policy به‌طور پیش‌فرض compat32 است.

_params به‌طور مستقیم به سازنده کلاس پایه ارسال می‌شوند.

تغییر یافته در نسخه‌ی 3.6: پارامتر فقط کلیدواژه‌ای policy اضافه شد.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

ماژول: email.mime.audio

کلاس MIMEAudio، یک زیرکلاس از MIMENonMultipart، برای ایجاد اشیای پیام MIME از نوع اصلی audio استفاده می‌شود. _audiodata شامل بایت‌های داده‌ی صوتی خام است. اگر این داده بتواند به‌صورت au، wav، aiff یا aifc کدگشایی شود، آنگاه زیرنوع به‌طور خودکار در سرآیند Content-Type درج می‌شود. در غیر این صورت می‌توانید زیرنوع صوتی را به‌صراحت از طریق آرگومان _subtype مشخص کنید. اگر نوع فرعی قابل حدس زدن نبود و _subtype داده نشد، آنگاه TypeError پرتاب می‌شود.

_encoder اختیاری یک فراخوانی‌پذیر (یعنی تابع) است که کدگذاری واقعی داده‌های صوتی برای انتقال را انجام می‌دهد. این فراخوانی‌پذیر یک آرگومان می‌گیرد، که نمونه‌ای از MIMEAudio است. باید از get_payload() و set_payload() برای تغییر بار به شکل کدگذاری‌شده استفاده کند. همچنین باید در صورت لزوم، سرآیند‌ی Content-Transfer-Encoding یا سایر سرآیند‌ها را به شیء پیام اضافه کند. کدگذاری پیش‌فرض، base64 است. برای فهرستی از کدگذارهای توکار، ماژول email.encoders را ببینید.

آرگومان اختیاری policy به‌طور پیش‌فرض compat32 است.

_params به‌طور مستقیم به سازنده کلاس پایه ارسال می‌شوند.

تغییر یافته در نسخه‌ی 3.6: پارامتر فقط کلیدواژه‌ای policy اضافه شد.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

ماژول: email.mime.image

کلاس MIMEImage یک زیرکلاس از MIMENonMultipart است و برای ایجاد اشیای پیام MIME با نوع اصلی image استفاده می‌شود. _imagedata شامل بایت‌های داده‌ی خام تصویر است. اگر این نوع داده قابل تشخیص باشد (jpeg، png، gif، tiff، rgb، pbm، pgm، ppm، rast، xbm، bmp، webp و exr بررسی می‌شوند)، آنگاه زیرنوع به‌طور خودکار در سرآیند Content-Type گنجانده می‌شود. در غیر این صورت می‌توانید زیرنوع تصویر را به‌صراحت از طریق آرگومان _subtype مشخص کنید. اگر نوع فرعی را نتوان حدس زد و _subtype داده نشده باشد، آنگاه TypeError پرتاب می‌شود.

_encoder اختیاری، یک فراخوانی‌پذیر (یعنی تابع) است که کدگذاری واقعی داده‌های تصویر برای انتقال را انجام می‌دهد. این فراخوانی‌پذیر یک آرگومان می‌گیرد که نمونه‌ی MIMEImage است. باید از get_payload() و set_payload() برای تغییر بار به‌صورت کدگذاری‌شده استفاده کند. همچنین باید در صورت لزوم، Content-Transfer-Encoding یا سایر سرآیند‌ها را به شیء پیام اضافه کند. کدگذاری پیش‌فرض، base64 است. برای دیدن فهرستی از کدگذارهای توکار، ماژول email.encoders را ببینید.

آرگومان اختیاری policy به‌طور پیش‌فرض compat32 است.

_params مستقیماً به سازنده‌ی MIMEBase ارسال می‌شوند.

تغییر یافته در نسخه‌ی 3.6: پارامتر فقط کلیدواژه‌ای policy اضافه شد.

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

ماژول: email.mime.message

کلاس MIMEMessage، زیرکلاسی از MIMENonMultipart، برای ساخت اشیای MIME از نوع اصلی message استفاده می‌شود. از _msg به‌عنوان بار استفاده می‌شود و باید نمونه‌ای از کلاس Message (یا زیرکلاسی از آن) باشد، در غیر این صورت TypeError پرتاب می‌شود.

_subtype اختیاری، زیرنوع پیام را تنظیم می‌کند؛ مقدار پیش‌فرض آن rfc822 است.

آرگومان اختیاری policy به‌طور پیش‌فرض compat32 است.

تغییر یافته در نسخه‌ی 3.6: پارامتر فقط کلیدواژه‌ای policy اضافه شد.

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

ماژول: email.mime.text

کلاس MIMEText، زیرکلاسی از MIMENonMultipart، برای ایجاد اشیاء MIME از نوع اصلی text استفاده می‌شود. _text رشته‌ای برای بار است. _subtype نوع فرعی است و پیش‌فرض آن plain است. _charset مجموعه نویسه‌ی متن است و به‌عنوان آرگومان به سازنده‌ی MIMENonMultipart ارسال می‌شود؛ اگر رشته فقط شامل نقاط کد ascii باشد، پیش‌فرض آن us-ascii و در غیر این صورت utf-8 است. پارامتر _charset یک رشته یا یک نمونه از Charset را می‌پذیرد.

مگر اینکه آرگومان _charset به‌صراحت روی None تنظیم شده باشد، شیء MIMEText ایجادشده هم یک سرآیند Content-Type با پارامتر charset و هم یک سرآیند Content-Transfer-Encoding خواهد داشت. این بدان معناست که فراخوانی بعدی set_payload به یک باری کدگذاری‌شده منجر نخواهد شد، حتی اگر یک نویسه‌گان در دستور set_payload داده شود. شما می‌توانید این رفتار را با حذف سرآیند Content-Transfer-Encoding «بازنشانی» کنید؛ پس از آن، فراخوانی set_payload به‌طور خودکار باری جدید را کدگذاری می‌کند (و یک سرآیند جدید Content-Transfer-Encoding را می‌افزاید).

آرگومان اختیاری policy به‌طور پیش‌فرض compat32 است.

تغییر یافته در نسخه‌ی 3.5: _charset همچنین نمونه‌های Charset را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.6: پارامتر فقط کلیدواژه‌ای policy اضافه شد.