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_encoding BASE64 باشد، رشته 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__() است.

__eq__(other)¶

این متد به شما امکان می‌دهد دو نمونه از Charset را از نظر برابری مقایسه کنید.

__ne__(other)¶

این متد به شما امکان می‌دهد دو نمونه از Charset را از نظر نابرابری مقایسه کنید.

ماژول 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 نگهداری می‌شود.

email.charset.add_codec(charset, codecname)¶

یک کدک اضافه کنید که نویسه‌های موجود در مجموعه نویسه داده‌شده را به یونیکد و از یونیکد نگاشت می‌کند.

charset نام کانونیکال مجموعه‌ای از نویسه‌ها است. codecname نام یک کدک پایتون است، مناسب برای آرگومان دوم متد encode() کلاس str.