email.charset: بازنمایی مجموعههای نویسهای¶
کد منبع: Lib/email/charset.py
این ماژول بخشی از API ایمیل قدیمی (Compat32) است. در API جدید، فقط از جدول نامهای مستعار استفاده میشود.
متن باقیمانده در این بخش، مستندات اصلی ماژول است.
این ماژول یک کلاس Charset برای بازنمایی مجموعهنویسهها و تبدیلهای مجموعهنویسهها در پیامهای ایمیل، و همچنین یک رجیستری مجموعهنویسهها و چند متد کمکی برای دستکاری این رجیستری فراهم میکند. نمونههای Charset در چند ماژول دیگر درون بسته email استفاده میشوند.
این کلاس را از ماژول email.charset ایمپورت کنید.
- class email.charset.Charset(input_charset=DEFAULT_CHARSET)¶
مجموعهنویسهها را به ویژگیهای ایمیلی آنها نگاشت میکند.
این کلاس اطلاعاتی درباره الزامات تحمیلشده بر ایمیل برای یک مجموعهنویسه خاص ارائه میدهد. همچنین روالهای آسانکنندهای برای تبدیل بین مجموعهنویسهها، با توجه به دسترسپذیری کدکهای مربوطه، ارائه میدهد. با داشتن یک مجموعهنویسه، این کلاس نهایت تلاش خود را میکند تا اطلاعاتی درباره نحوه استفاده از آن مجموعهنویسه در یک پیام ایمیل به شیوهای منطبق با RFC ارائه دهد.
برخی مجموعههای نویسه باید هنگام استفاده در سرآیندها یا بدنههای ایمیل با quoted-printable یا base64 کدگذاری شوند. برخی مجموعههای نویسه باید بهطور کامل تبدیل شوند و در ایمیل مجاز نیستند.
input_charset اختیاری همانگونه است که در ادامه توضیح داده شده است؛ این مقدار همیشه به حروف کوچک تبدیل میشود. پس از نرمالسازی نام مستعار، از آن برای جستوجو در فهرست ثبت مجموعههای نویسهای نیز استفاده میشود تا کدگذاری سرآیند، کدگذاری بدنه و کدک تبدیل خروجی مورد استفاده برای آن مجموعه نویسهای مشخص شود. برای مثال، اگر input_charset برابر
iso-8859-1باشد، سرآیندها و بدنهها با استفاده از quoted-printable کدگذاری میشوند و نیازی به کدک تبدیل خروجی نیست. اگر input_charset برابرeuc-jpباشد، سرآیندها با base64 کدگذاری میشوند، بدنهها کدگذاری نمیشوند، اما متن خروجی از مجموعه نویسهایeuc-jpبه مجموعه نویسهایiso-2022-jpتبدیل میشود.نمونههای
Charsetدارای ویژگیهای دادهای زیر هستند:- input_charset¶
مجموعه نویسهی اولیهی مشخصشده. نامهای مستعار رایج به نامهای ایمیلی رسمی خود تبدیل میشوند (برای مثال
latin_1بهiso-8859-1تبدیل میشود). مقدار پیشفرض آنus-ascii۷ بیتی است.
- header_encoding¶
اگر لازم باشد مجموعه نویسهها پیش از استفاده در سرآیند ایمیل کدگذاری شود، این ویژگی روی
charset.QP(برای quoted-printable)،charset.BASE64(برای کدگذاری base64) یاcharset.SHORTESTبرای کوتاهترین حالت بین کدگذاری QP و BASE64 تنظیم میشود. در غیر این صورت،Noneخواهد بود.
- body_encoding¶
مشابه header_encoding، اما کدگذاری بدنهی پیام ایمیل را توصیف میکند، که در واقع ممکن است با کدگذاری سرآیند متفاوت باشد.
charset.SHORTESTبرای body_encoding مجاز نیست.
- output_charset¶
برخی مجموعهنویسهها باید پیش از استفاده در سرآیندها یا بدنههای ایمیل تبدیل شوند. اگر input_charset یکی از آنها باشد، این ویژگی شامل نام مجموعهنویسهای خواهد بود که خروجی به آن تبدیل میشود. در غیر این صورت،
Noneخواهد بود.
- input_codec¶
نام کدک پایتون استفادهشده برای تبدیل input_charset به یونیکد. اگر نیازی به کدک تبدیل نباشد، این ویژگی
Noneخواهد بود.
- output_codec¶
نام کدک پایتون که برای تبدیل یونیکد به output_charset استفاده میشود. اگر به کدک تبدیل نیازی نباشد، این ویژگی همان مقدار input_codec را خواهد داشت.
نمونههای
Charsetهمچنین دارای متدهای زیر هستند:- get_body_encoding()¶
کدگذاری انتقال محتوا را که برای کدگذاری بدنه استفاده میشود، برمیگرداند.
این مقدار بسته به کدگذاری استفادهشده، یا رشته
quoted-printableاست یاbase64، یا یک تابع است؛ در این صورت باید تابع را با یک آرگومان فراخوانی کنید: شیء Message که کدگذاری میشود. سپس تابع باید خودش سرآیند Content-Transfer-Encoding را روی هر مقداری که مناسب است تنظیم کند.اگر body_encoding
QPباشد، رشتهquoted-printableرا برمیگرداند، اگر body_encodingBASE64باشد، رشتهbase64را برمیگرداند، و در غیر این صورت رشته7bitرا برمیگرداند.
- get_output_charset()¶
مجموعه نویسههای خروجی را برمیگرداند.
این ویژگی output_charset است اگر آن
Noneنباشد، در غیر این صورت input_charset است.
- header_encode(string)¶
رشتهی string را بهصورت سرآیند کدگذاری کنید.
نوع کدگذاری (base64 یا quoted-printable) بر اساس ویژگی header_encoding خواهد بود.
- header_encode_lines(string, maxlengths)¶
یک string را با تبدیل آن به بایتها در ابتدا، کدگذاری سرآیند (Header-encode) کنید.
این مشابه
header_encode()است، با این تفاوت که رشته در حداکثر طولهای خط دادهشده توسط آرگومان maxlengths، که باید یک پیمایشگر باشد، جای داده میشود: هر عنصری که از این پیمایشگر بازگردانده شود، حداکثر طول خط بعدی را فراهم میکند.
- body_encode(string)¶
رشتهی string را کدگذاری بدنه کنید.
نوع کدگذاری (base64 یا quoted-printable) بر اساس ویژگی body_encoding خواهد بود.
کلاس
Charsetهمچنین تعدادی متد برای پشتیبانی از عملیات استاندارد و توابع توکار فراهم میکند.- __str__()¶
input_charset را بهصورت رشتهای که به حروف کوچک تبدیلشده است برمیگرداند.
__repr__()نام مستعاری برای__str__()است.
ماژول email.charset همچنین توابع زیر را برای افزودن ورودیهای جدید به رجیستریهای سراسری مجموعهنویسه، نام مستعار و کدک فراهم میکند:
- email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)¶
ویژگیهای نویسه را به رجیستری سراسری اضافه کنید.
charset مجموعه نویسههای ورودی است و باید نام کانونیکال یک مجموعه نویسه باشد.
header_enc و body_enc اختیاری میتوانند یکی از مقادیر زیر باشند:
charset.QPبرای کدگذاری quoted-printable،charset.BASE64برای کدگذاری base64،charset.SHORTESTبرای کوتاهترین حالت از کدگذاری quoted-printable یا base64، یاNoneبرای بدون کدگذاری.SHORTESTفقط برای header_enc معتبر است. مقدار پیشفرضNoneبرای بدون کدگذاری است.output_charset اختیاری، مجموعه نویسهای است که خروجی باید با آن باشد. هنگامی که متد
Charset.convert()فراخوانی میشود، تبدیلها از مجموعه نویسه ورودی، به یونیکد و سپس به مجموعه نویسه خروجی انجام میشوند. بهطور پیشفرض، خروجی با همان مجموعه نویسه ورودی خواهد بود.هر دو input_charset و output_charset باید دارای مداخل کدک یونیکد در نگاشت مجموعه نویسه به کدک ماژول باشند؛ برای افزودن کدکهایی که ماژول آنها را نمیشناسد، از
add_codec()استفاده کنید. برای اطلاعات بیشتر، مستندات ماژولcodecsرا ببینید.ثبت سراسری مجموعه نویسهها در دیکشنری سراسری ماژول
CHARSETSنگهداری میشود.
- email.charset.add_alias(alias, canonical)¶
یک نام مستعار برای مجموعه نویسه اضافه کنید. alias نام مستعار است، مثلاً
latin-1. canonical نام کانونیکال مجموعه نویسه است، مثلاًiso-8859-1.ثبت سراسری نامهای مستعار مجموعهنویسه در دیکشنری سراسری ماژول
ALIASESنگهداری میشود.