email.policy: اشیاء Policy

اضافه شده در نسخه‌ی 3.3.

کد منبع: Lib/email/policy.py

تمرکز اصلی بسته‌ی email پردازش پیام‌های ایمیلی است، همان‌گونه که در RFCهای مختلف ایمیل و MIME توصیف شده است. با این حال، قالب کلی پیام‌های ایمیلی (بلوکی از فیلدهای سرآیند که هر یک شامل یک نام، به‌دنبال آن یک دونقطه و به‌دنبال آن یک مقدار است و کل بلوک با یک خط خالی و یک «بدنه» دلخواه دنبال می‌شود)، قالبی است که فراتر از حوزه‌ی ایمیل نیز کاربرد یافته است. برخی از این کاربردها تا حد زیادی با RFCهای اصلی ایمیل مطابقت دارند، برخی مطابقت ندارند. حتی هنگام کار با ایمیل، گاهی اوقات خروج از انطباق دقیق با RFCها مطلوب است، مانند تولید ایمیل‌هایی که با سرورهای ایمیلی که خودشان استانداردها را رعایت نمی‌کنند یا افزونه‌هایی را پیاده‌سازی می‌کنند که می‌خواهید به روش‌هایی که استانداردها را نقض می‌کنند از آن‌ها استفاده کنید، تعامل دارند.

اشیای Policy به بسته‌ی email انعطاف‌پذیری می‌دهند تا تمام این موارد استفاده‌ی متفاوت را مدیریت کند.

یک شیء Policy مجموعه‌ای از ویژگی‌ها و متدها را در بر می‌گیرد که رفتار کامپوننت‌های مختلف بسته‌ی email را در هنگام استفاده کنترل می‌کنند. می‌توان نمونه‌های Policy را به کلاس‌ها و متدهای مختلف بسته‌ی email ارسال کرد تا رفتار پیش‌فرض تغییر کند. مقادیر قابل‌تنظیم و پیش‌فرض‌های آن‌ها در زیر توضیح داده شده‌اند.

یک سیاست پیش‌فرض وجود دارد که توسط همه‌ی کلاس‌های بسته‌ی email استفاده می‌شود. برای همه‌ی کلاس‌های parser و توابع سهولت‌بخش مرتبط، و برای کلاس Message، این سیاست Compat32 است، از طریق نمونه‌ی از پیش تعریف‌شده‌ی متناظر آن compat32. این سیاست سازگاری کامل رو به عقب (در برخی موارد، شامل سازگاری با اشکال‌ها) با نسخه‌ی پیش از Python3.3 بسته‌ی email را فراهم می‌کند.

این مقدار پیش‌فرض برای کلیدواژه‌ی policy در EmailMessage، سیاست EmailPolicy است که از طریق نمونه‌ی از پیش تعریف‌شده‌ی آن، default، فراهم می‌شود.

هنگامی که یک شیء Message یا EmailMessage ایجاد می‌شود، یک سیاست کسب می‌کند. اگر پیام توسط یک parser ایجاد شود، سیاستی که به پارسر ارسال شود، سیاستی خواهد بود که پیام ایجادشده از آن استفاده می‌کند. اگر پیام توسط برنامه ایجاد شود، می‌توان سیاست را هنگام ایجاد آن مشخص کرد. هنگامی که یک پیام به یک generator ارسال می‌شود، تولیدگر به‌طور پیش‌فرض از سیاست پیام استفاده می‌کند، اما می‌توانید یک سیاست مشخص را نیز به تولیدگر ارسال کنید که جایگزین سیاست ذخیره‌شده در شیء پیام می‌شود.

مقدار پیش‌فرض برای کلیدواژه‌ی policy در کلاس‌های email.parser و توابع سهولت‌بخش پارسر، در نسخه‌ای آینده از پایتون تغییر خواهد کرد. بنابراین شما باید هنگام فراخوانی هر یک از کلاس‌ها و توابع توصیف‌شده در ماژول parser، همیشه به‌صورت صریح مشخص کنید که می‌خواهید از کدام policy استفاده کنید.

بخش نخست این مستندات قابلیت‌های Policy، یک abstract base class که قابلیت‌های مشترک میان تمام اشیای سیاست، از جمله compat32، را تعریف می‌کند، پوشش می‌دهد. این قابلیت‌ها شامل برخی متدهای قلاب هستند که به‌صورت داخلی توسط بسته email فراخوانی می‌شوند و یک سیاست سفارشی می‌تواند آن‌ها را برای به دست آوردن رفتاری متفاوت بازنویسی کند. بخش دوم کلاس‌های عینی EmailPolicy و Compat32 را توصیف می‌کند، که به‌ترتیب قلاب‌هایی را پیاده‌سازی می‌کنند که رفتار استاندارد و رفتار و قابلیت‌های سازگار با نسخه‌های قدیمی را فراهم می‌کنند.

نمونه‌های Policy تغییرناپذیر هستند، اما می‌توان آن‌ها را همانندسازی کرد؛ این عملیات همان آرگومان‌های کلیدواژه‌ای سازنده‌ی کلاس را می‌پذیرد و یک نمونه‌ی جدید از Policy بازمی‌گرداند که کپی نمونه‌ی اصلی است، اما مقادیر ویژگی‌های مشخص‌شده در آن تغییر کرده‌اند.

برای مثال، می‌توان از کد زیر برای خواندن یک پیام ایمیل از یک پرونده روی دیسک و ارسال آن به برنامه sendmail سیستم در یک سیستم یونیکس استفاده کرد:

>>> from email import message_from_binary_file
>>> from email.generator import BytesGenerator
>>> from email import policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'rb') as f:
...     msg = message_from_binary_file(f, policy=policy.default)
...
>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)
>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()

در اینجا ما به BytesGenerator می‌گوییم که هنگام ایجاد رشته دودویی برای فرستادن به sendmail's stdin، از نویسه‌های جداکننده خط صحیح مطابق RFC استفاده کند، در حالی که سیاست پیش‌فرض از جداکننده‌های خط \n استفاده می‌کرد.

برخی از متدهای بسته‌ی email آرگومان کلیدواژه‌ای policy را می‌پذیرند، که امکان جایگزینی سیاست برای آن متد را فراهم می‌کند. برای مثال، کد زیر از متد as_bytes() شیء msg از مثال پیشین استفاده می‌کند و پیام را با استفاده از جداکننده‌های خط بومیِ سکویی که روی آن اجرا می‌شود، در یک پرونده می‌نویسد:

>>> import os
>>> with open('converted.txt', 'wb') as f:
...     f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17

همچنین می‌توان با استفاده از عملگر جمع، اشیای Policy را ترکیب کرد و به یک شیء Policy رسید که تنظیمات آن ترکیبی از مقادیر غیرپیش‌فرض اشیای جمع‌شده است:

>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict

این عملیات جابه‌جایی‌پذیر نیست؛ یعنی ترتیبی که اشیاء اضافه می‌شوند اهمیت دارد. برای نمونه:

>>> policy100 = policy.compat32.clone(max_line_length=100)
>>> policy80 = policy.compat32.clone(max_line_length=80)
>>> apolicy = policy100 + policy80
>>> apolicy.max_line_length
80
>>> apolicy = policy80 + policy100
>>> apolicy.max_line_length
100
class email.policy.Policy(**kw)

این کلاس پایه انتزاعی برای تمام کلاس‌های سیاست است. این کلاس پیاده‌سازی‌های پیش‌فرضی برای چند متد ساده، و همچنین پیاده‌سازی ویژگی تغییرناپذیری، متد clone() و معنای سازنده را ارائه می‌دهد.

سازنده‌ی یک کلاس سیاست می‌تواند آرگومان‌های کلیدواژه‌ای مختلفی را بپذیرد. آرگومان‌هایی که می‌توان مشخص کرد، شامل هر پراپرتی غیرمتدی این کلاس، به‌علاوه‌ی هر پراپرتی غیرمتدی اضافه‌ای در کلاس عینی می‌شوند. مقداری که در سازنده مشخص شود، مقدار پیش‌فرض ویژگی متناظر را بازنویسی می‌کند.

این کلاس ویژگی‌های زیر را تعریف می‌کند، بنابراین مقادیر موارد زیر می‌توانند به سازنده‌ی هر کلاس سیاست پاس داده شوند:

max_line_length

حداکثر طول هر خط در خروجی سریال‌شده، بدون احتساب نویسه(های) پایان خط. مقدار پیش‌فرض ۷۸ است، مطابق RFC 5322. مقدار 0 یا None نشان می‌دهد که به‌هیچ‌وجه نباید سطرهای شکسته شوند.

linesep

رشته‌ای که برای پایان‌دادن به سطرها در خروجی سریال‌سازی‌شده استفاده می‌شود. مقدار پیش‌فرض \n است، زیرا این قاعده‌ی درونی پایان سطری است که پایتون از آن استفاده می‌کند، اگرچه \r\n توسط RFCها الزامی شده است.

cte_type

نوع کدگذاری‌های انتقال محتوارا که ممکن است استفاده شوند یا استفاده از آن‌ها الزامی باشد، کنترل می‌کند. مقادیر ممکن عبارت‌اند از:

7bit

تمام داده‌ها باید «7 bit clean» (فقط ASCII) باشند. این بدان معناست که در صورت لزوم، داده‌ها با استفاده از کدگذاری quoted-printable یا base64 کدگذاری می‌شوند.

8bit

داده محدود نیست که ۷ بیتی پاک (7 bit clean) باشد. داده‌های موجود در سرآیند‌ها همچنان باید فقط ASCII باشند و بنابراین کدگذاری خواهند شد (برای موارد استثنا، fold_binary() و utf8 را در زیر ببینید)، اما بخش‌های بدنه می‌توانند از CTE 8bit استفاده کنند.

مقدار 8bit برای cte_type فقط با BytesGenerator کار می‌کند، نه Generator، زیرا رشته‌ها نمی‌توانند حاوی داده‌های دودویی باشند. اگر یک Generator تحت سیاستی کار کند که cte_type=8bit را تعیین کرده باشد، به‌گونه‌ای رفتار می‌کند که گویی cte_type برابر 7bit است.

raise_on_defect

اگر True باشد، هر نقصی که با آن مواجه شود به‌عنوان خطا پرتاب خواهد شد. اگر False باشد (پیش‌فرض)، نقص‌ها به متد register_defect() ارسال می‌شوند.

mangle_from_

اگر True باشد، سطرهایی که در بدنه با "From " شروع می‌شوند، با قرار دادن یک > در ابتدای آن‌ها خنثی می‌شوند. این پارامتر زمانی استفاده می‌شود که پیام توسط یک تولیدگر سریال‌سازی می‌شود. پیش‌فرض: False.

اضافه شده در نسخه‌ی 3.5.

message_factory

یک تابع کارخانه‌ای (factory function) برای ساختن یک شیء پیام خالی جدید. توسط پارسر هنگام ساخت پیام‌ها استفاده می‌شود. پیش‌فرض آن None است، که در این صورت از Message استفاده می‌شود.

اضافه شده در نسخه‌ی 3.6.

verify_generated_headers

اگر True باشد (پیش‌فرض)، تولیدگر به‌جای نوشتن سرآیندی که به‌شکل نادرست تاخورده یا مرزبندی‌شده است، به‌گونه‌ای که به‌عنوان چند سرآیند تجزیه شود یا با داده‌های مجاور ادغام گردد، HeaderWriteError را پرتاب می‌کند. چنین سرآیندهایی ممکن است توسط کلاس‌های سرآیند سفارشی یا به‌دلیل اشکالات ماژول email تولید شوند.

از آنجا که این یک ویژگی امنیتی است، مقدار پیش‌فرض آن حتی در سیاست Compat32 برابر True است. برای رفتار سازگار با عقب‌گرد، اما ناامن، باید به‌صراحت روی False تنظیم شود.

اضافه شده در نسخه‌ی 3.13.

متد Policy زیر برای فراخوانی توسط کدی در نظر گرفته شده است که از کتابخانه email برای ایجاد نمونه‌های سیاست با تنظیمات سفارشی استفاده می‌کند:

clone(**kw)

یک نمونه جدید از Policy برمی‌گرداند که ویژگی‌های آن مقادیری مشابه مقادیر نمونه فعلی دارند، مگر در مواردی که مقادیر جدیدی به آن ویژگی‌ها توسط آرگومان‌های کلیدواژه‌ای داده شده باشد.

متدهای باقی‌مانده‌ی Policy توسط کد بسته‌ی email فراخوانی می‌شوند و برای فراخوانی توسط برنامه‌ای که از بسته‌ی email استفاده می‌کند، در نظر گرفته نشده‌اند. یک سیاست سفارشی باید تمام این متدها را پیاده‌سازی کند.

handle_defect(obj, defect)

یک defect یافت‌شده در obj را مدیریت کنید. وقتی بسته‌ی email این متد را فراخوانی می‌کند، defect همواره یک زیرکلاس از MessageDefect خواهد بود.

پیاده‌سازی پیش‌فرض، پرچم raise_on_defect را بررسی می‌کند. اگر True باشد، defect به‌عنوان یک استثنا پرتاب می‌شود. اگر False باشد (حالت پیش‌فرض)، obj و defect به register_defect() ارسال می‌شوند.

register_defect(obj, defect)

یک defect را روی obj ثبت کنید. در بسته‌ی email، defect همواره زیرکلاسی از MessageDefect خواهد بود.

پیاده‌سازی پیش‌فرض، متد append ویژگی defects متعلق به obj را فراخوانی می‌کند. هنگامی که بسته email، handle_defect را فراخوانی می‌کند، obj معمولاً دارای یک ویژگی defects خواهد بود که متد append دارد. انواع اشیاء سفارشی که با بسته email استفاده می‌شوند (برای مثال، اشیاء Message سفارشی) نیز باید چنین ویژگی‌ای را فراهم کنند، در غیر این صورت نقص‌های موجود در پیام‌های تجزیه‌شده باعث پرتاب خطاهای غیرمنتظره‌ای خواهند شد.

header_max_count(name)

بیشینه تعداد مجاز سرآیندهایی با نام name را برمی‌گرداند.

هنگامی که یک سرآیند به یک شیء EmailMessage یا Message اضافه شود، فراخوانی می‌شود. اگر مقدار بازگشتی 0 یا None نباشد، و تعداد سرآیندهایی که از قبل با نام name وجود دارند، بزرگ‌تر یا مساوی با مقدار بازگشتی باشد، یک ValueError پرتاب می‌شود.

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

پیاده‌سازی پیش‌فرض برای همه‌ی نام‌های سرآیند None را برمی‌گرداند.

header_source_parse(sourcelines)

بسته‌ی email این متد را با فهرستی از رشته‌ها فراخوانی می‌کند، که هر رشته با نویسه‌های جداکننده‌ی خط موجود در منبع در حال تجزیه پایان می‌یابد. خط اول شامل نام فیلد سرآیند و جداکننده است. تمام فضای خالی موجود در منبع حفظ می‌شود. این متد باید تاپل (name, value) را برگرداند که قرار است در Message ذخیره شود تا سرآیند تجزیه‌شده را نشان دهد.

اگر یک پیاده‌سازی بخواهد سازگاری با سیاست‌های موجود بسته email را حفظ کند، name باید نام با حفظ بزرگی و کوچکی حروف باشد (همه نویسه‌ها تا پیش از جداکننده ':')، در حالی که value باید مقدار بازشده باشد (همه نویسه‌های جداکننده خط حذف شده‌اند، اما فضای سفید دست‌نخورده باقی مانده است) و فضای سفید ابتدایی آن حذف شده باشد.

sourcelines ممکن است حاوی داده‌های دودویی surrogateescaped باشد.

هیچ پیاده‌سازی پیش‌فرضی وجود ندارد

header_store_parse(name, value)

بسته‌ی email این متد را با نام و مقدار ارائه‌شده توسط برنامه‌ی کاربردی، هنگامی که برنامه‌ی کاربردی در حال تغییر یک Message به‌صورت برنامه‌ای است (در مقابل یک Message که توسط یک پارسر ایجاد شده است)، فراخوانی می‌کند. این متد باید تاپل (name, value) را که قرار است در Message ذخیره شود تا نشان‌دهنده‌ی سرآیند باشد، برگرداند.

اگر یک پیاده‌سازی بخواهد سازگاری با سیاست‌های موجود در بسته email را حفظ کند، name و value باید رشته‌ها یا زیرکلاس‌های رشته باشند که محتوای آرگومان‌های داده‌شده را تغییر نمی‌دهند.

هیچ پیاده‌سازی پیش‌فرضی وجود ندارد

header_fetch_parse(name, value)

بسته‌ی email این متد را هنگامی که برنامه کاربردی آن سرآیند را درخواست کند، با name و value ذخیره‌شده در Message فراخوانی می‌کند، و هر آنچه این متد برمی‌گرداند، همان چیزی است که به‌عنوان مقدار سرآیندی که واکشی می‌شود، به برنامه کاربردی بازگردانده می‌شود. توجه داشته باشید که ممکن است بیش از یک سرآیند با نام یکسان در Message ذخیره‌شده باشد؛ به این متد نام و مقدار مشخص سرآیندی که قرار است به برنامه کاربردی بازگردانده شود، داده می‌شود.

ممکن است value حاوی داده‌های دودویی surrogateescaped باشد. نباید هیچ داده‌ی دودویی surrogateescaped در مقداری که متد برمی‌گرداند وجود داشته باشد.

هیچ پیاده‌سازی پیش‌فرضی وجود ندارد

fold(name, value)

بسته‌ی email این متد را با name و value که در حال حاضر در Message برای یک سرآیند مشخص ذخیره شده‌اند، فراخوانی می‌کند. این متد باید با ترکیب name با value و درج نویسه‌های linesep در محل‌های مناسب، رشته‌ای برگرداند که آن سرآیند را به‌درستی به‌صورت «تا شده (folded)» (بر اساس تنظیمات سیاست) نشان می‌دهد. برای بحث درباره‌ی قوانین تا کردن (folding) سرآیندهای ایمیل، RFC 5322 را ببینید.

value ممکن است حاوی داده‌های دودویی surrogateescaped باشد. رشته‌ای که این متد برمی‌گرداند نباید حاوی داده‌های دودویی surrogateescaped باشد.

fold_binary(name, value)

مشابه fold()، با این تفاوت که مقدار بازگشتی باید به جای یک رشته، یک شیء بایتی باشد.

value ممکن است حاوی داده‌های دودویی surrogateescaped باشد. این داده‌ها می‌توانند در شیء bytes برگردانده‌شده دوباره به داده‌های دودویی تبدیل شوند.

class email.policy.EmailPolicy(**kw)

این Policy ملموس، رفتاری را فراهم می‌کند که هدف آن انطباق کامل با RFCهای فعلی ایمیل است. این RFCها شامل (اما نه محدود به) RFC 5322، RFC 2047 و RFCهای فعلی MIME هستند.

این سیاست الگوریتم‌های جدیدی برای تجزیه و تا کردن سرآیند‌ها اضافه می‌کند. به‌جای رشته‌های ساده، سرآیند‌ها زیرکلاس‌هایی از str هستند که ویژگی‌هایی وابسته به نوع فیلد دارند. الگوریتم تجزیه و تا کردن، RFC 2047 و RFC 5322 را به‌طور کامل پیاده‌سازی می‌کند.

مقدار پیش‌فرض برای ویژگی message_factory، EmailMessage است.

علاوه بر ویژگی‌های قابل تنظیم فهرست‌شده در بالا که به همه‌ی سیاست‌ها اعمال می‌شوند، این سیاست ویژگی‌های اضافی زیر را اضافه می‌کند:

اضافه شده در نسخه‌ی 3.6: [1]

utf8

اگر False باشد، از RFC 5322 پیروی می‌کند و با کدگذاری نویسه‌های غیر ASCII موجود در سرآیندها به‌عنوان «کلمات کدگذاری‌شده»، از آن‌ها پشتیبانی می‌کند. اگر True باشد، از RFC 6532 پیروی می‌کند و برای سرآیندها از کدگذاری utf-8 استفاده می‌کند. پیام‌هایی که به این شکل قالب‌بندی شده‌اند، می‌توانند به سرورهای SMTP که از افزونه SMTPUTF8 پشتیبانی می‌کنند (RFC 6531) ارسال شوند.

refold_source

اگر مقدار یک سرآیند در شیء Message از parser آمده باشد (در مقابل تنظیم شدن توسط یک برنامه)، این ویژگی نشان می‌دهد که آیا یک تولیدگر باید آن مقدار را هنگام بازگرداندن پیام به قالب سریالی‌شده دوباره تا بزند (refold) یا خیر. مقادیر ممکن عبارت‌اند از:

none

همه‌ی مقادیر منبع از تا کردن اصلی استفاده می‌کنند

long

مقادیر مبدأ که هر یک از سطرهایشان طولانی‌تر از max_line_length باشد، دوباره تا خواهند شد

all

تمام مقادیر دوباره تا می‌شوند.

مقدار پیش‌فرض long است.

header_factory

یک شیء فراخوانی‌پذیر که دو آرگومان name و value را می‌گیرد؛ در اینجا name نام فیلد سرآیند و value مقدار فیلد سرآیند بازشده (unfolded) است، و نمونه‌ای از یک زیرکلاس رشته را برمی‌گرداند که نمایانگر آن سرآیند است. یک header_factory پیش‌فرض (به headerregistry مراجعه کنید) فراهم شده است که از تجزیه سفارشی برای انواع مختلف فیلد سرآیند نشانی و تاریخ RFC 5322 و انواع اصلی فیلد سرآیند MIME پشتیبانی می‌کند. پشتیبانی از تجزیه سفارشی بیشتر در آینده افزوده خواهد شد.

content_manager

یک شیء با حداقل دو متد: get_content و set_content. هنگامی که متد get_content() یا set_content() از یک شیء EmailMessage فراخوانی می‌شود، متد متناظر این شیء را فراخوانی می‌کند و شیء پیام را به‌عنوان اولین آرگومان آن و هر آرگومان یا کلیدواژه‌ای را که به آن ارسال شده است، به‌عنوان آرگومان‌های اضافی به آن منتقل می‌کند. به‌طور پیش‌فرض content_manager روی raw_data_manager تنظیم شده است.

اضافه شده در نسخه‌ی 3.4.

این کلاس پیاده‌سازی‌های عینی زیر را برای متدهای انتزاعی Policy ارائه می‌دهد:

header_max_count(name)

مقدار ویژگی max_count کلاس تخصصی استفاده‌شده برای نمایش سرآیند با نام داده‌شده را برمی‌گرداند.

header_source_parse(sourcelines)

نام به‌عنوان همه‌چیز تا ':' تجزیه می‌شود و بدون تغییر بازگردانده می‌شود. مقدار با حذف فضای سفید ابتدایی از باقی‌مانده خط اول، به هم پیوستن تمام سطرهای بعدی و حذف هرگونه نویسه بازگشت به ابتدای سطر یا خط جدید در انتها تعیین می‌شود.

header_store_parse(name, value)

نام بدون تغییر بازگردانده می‌شود. اگر مقدار ورودی دارای ویژگی name باشد و آن با name بدون در نظر گرفتن بزرگی و کوچکی حروف مطابقت داشته باشد، مقدار بدون تغییر بازگردانده می‌شود. در غیر این صورت name و value به header_factory داده می‌شوند و شیء سرآیند حاصل به‌عنوان مقدار بازگردانده می‌شود. در این حالت اگر مقدار ورودی شامل نویسه‌های CR یا LF باشد، یک ValueError پرتاب می‌شود.

header_fetch_parse(name, value)

If the value has a name attribute, it is returned to unmodified. Otherwise the name, and the value with any CR or LF characters removed, are passed to the header_factory, and the resulting header object is returned. Any surrogateescaped bytes get turned into the Unicode unknown-character glyph.

fold(name, value)

تا کردن سرآیند با تنظیم سیاست refold_source کنترل می‌شود. یک مقدار اگر و تنها اگر ویژگی name نداشته باشد، یک «مقدار منبع» در نظر گرفته می‌شود (داشتن ویژگی name به این معناست که آن مقدار به نوعی یک شیء سرآیند است). اگر یک مقدار منبع نیاز داشته باشد طبق سیاست دوباره تا شود، با ارسال name و value به header_factory — پس از حذف همه نویسه‌های CR و LF — به یک شیء سرآیند تبدیل می‌شود. تا کردن یک شیء سرآیند با فراخوانی متد fold آن با سیاست جاری انجام می‌شود.

مقادیر منبع با استفاده از splitlines() به سطرهای تقسیم می‌شوند. اگر قرار نباشد مقدار دوباره تا شود، سطرهای با استفاده از linesep از سیاست دوباره به هم پیوسته و برگردانده می‌شوند. استثنا، سطرهایی هستند که حاوی داده‌های دودویی غیر ASCII هستند. در این صورت، مقدار صرف‌نظر از تنظیم refold_source دوباره تا می‌شود که باعث می‌شود داده‌های دودویی با استفاده از مجموعه‌نویسه unknown-8bit به‌صورت CTE کدگذاری شوند.

fold_binary(name, value)

اگر cte_type برابر 7bit باشد، همانند fold() است، با این تفاوت که مقدار بازگشتی bytes است.

اگر cte_type برابر 8bit باشد، داده دودویی غیر ASCII به بایت‌ها بازگردانده می‌شود. سرآیند‌های حاوی داده دودویی، صرف‌نظر از تنظیم refold_header، دوباره تا زده نمی‌شوند، زیرا هیچ راهی برای دانستن اینکه داده دودویی از نویسه‌های تک‌بایتی تشکیل شده است یا نویسه‌های چندبایتی، وجود ندارد.

نمونه‌های زیر از EmailPolicy پیش‌فرض‌هایی مناسب برای حوزه‌های کاربردی خاص فراهم می‌کنند. توجه داشته باشید که در آینده ممکن است رفتار این نمونه‌ها (به‌ویژه نمونه HTTP) تنظیم شود تا حتی نزدیک‌تر با RFCهای مرتبط با حوزه‌هایشان انطباق داشته باشد.

email.policy.default

نمونه‌ای از EmailPolicy که تمام پیش‌فرض‌های آن بدون تغییر هستند. این سیاست به‌جای پایان سطرهای \r\n مطابق RFC، از پایان سطرهای \n استاندارد پایتون استفاده می‌کند.

email.policy.SMTP

مناسب برای سریال‌سازی پیام‌ها مطابق با RFCهای ایمیل. مانند default، اما با linesep تنظیم‌شده روی \r\n، که مطابق با RFC است.

email.policy.SMTPUTF8

مانند SMTP است، با این تفاوت که utf8 برابر True است. برای سریال‌سازی پیام‌ها به یک مخزن پیام بدون استفاده از واژه‌های کدگذاری‌شده در سرآیندها مفید است. فقط باید زمانی برای انتقال از طریق SMTP از آن استفاده شود که آدرس‌های فرستنده یا گیرنده دارای نویسه‌های غیرASCII باشند (متد smtplib.SMTP.send_message() این مورد را به‌طور خودکار مدیریت می‌کند).

email.policy.HTTP

مناسب برای سریال‌سازی سرآیندها جهت استفاده در ترافیک HTTP. مانند SMTP، با این تفاوت که max_line_length روی None تنظیم شده است (نامحدود).

email.policy.strict

نمونه‌ی کمکی. همان default است، با این تفاوت که raise_on_defect روی True تنظیم شده است. این امکان را می‌دهد که هر سیاستی با نوشتن:: سخت‌گیرانه شود

somepolicy + policy.strict

با تمام این EmailPolicies، API مؤثر بسته‌ی email به‌صورت‌های زیر نسبت به API پایتون 3.2 تغییر کرده است:

  • تنظیم یک سرآیند روی یک Message باعث می‌شود آن سرآیند تجزیه شود و یک شیء سرآیند ایجاد گردد.

  • واکشی مقدار یک سرآیند از یک Message باعث می‌شود آن سرآیند تجزیه شود و یک شیء سرآیند ایجاد و برگردانده شود.

  • هر شیء سرآیند، یا هر سرآیندی که به‌دلیل تنظیمات سیاست دوباره تا می‌شود، با استفاده از الگوریتمی تا می‌شود که الگوریتم‌های تا کردن RFC را به‌طور کامل پیاده‌سازی می‌کند، از جمله این‌که می‌داند واژه‌های کدگذاری‌شده در کجا الزامی و مجاز هستند.

From the application view, this means that any header obtained through the EmailMessage is a header object with extra attributes, whose string value is the fully decoded value of the header. Likewise, a header may be assigned a new value, or a new header created, using a string, and the policy will take care of converting the string into the correct RFC encoded form.

اشیای سرآیند و ویژگی‌های آن‌ها در headerregistry شرح داده شده‌اند.

class email.policy.Compat32(**kw)

این Policy عینی، سیاست سازگاری با عقب است. این رفتار بسته‌ی email در Python 3.2 را بازتولید می‌کند. ماژول policy همچنین یک نمونه از این کلاس، compat32، را تعریف می‌کند که به‌عنوان سیاست پیش‌فرض استفاده می‌شود. بنابراین رفتار پیش‌فرض بسته‌ی email، حفظ سازگاری با Python 3.2 است.

ویژگی‌های زیر مقادیری متفاوت با پیش‌فرض Policy دارند:

mangle_from_

مقدار پیش‌فرض True است.

این کلاس پیاده‌سازی‌های عینی زیر را برای متدهای انتزاعی Policy ارائه می‌دهد:

header_source_parse(sourcelines)

نام به‌عنوان همه‌چیز تا ':' تجزیه می‌شود و بدون تغییر بازگردانده می‌شود. مقدار با حذف فضای سفید ابتدایی از باقی‌مانده خط اول، به هم پیوستن تمام سطرهای بعدی و حذف هرگونه نویسه بازگشت به ابتدای سطر یا خط جدید در انتها تعیین می‌شود.

header_store_parse(name, value)

نام و مقدار بدون تغییر بازگردانده می‌شوند.

header_fetch_parse(name, value)

اگر مقدار شامل داده‌های دودویی باشد، با استفاده از مجموعه‌نویسه unknown-8bit به یک شیء Header تبدیل می‌شود. در غیر این صورت، بدون تغییر بازگردانده می‌شود.

fold(name, value)

سرآیندها با استفاده از الگوریتم تا کردن کلاس Header تا می‌شوند، که شکستگی‌های خط موجود در مقدار را حفظ می‌کند و هر خط حاصل را تا max_line_length می‌شکند. داده‌های دودویی غیر ASCII با استفاده از نویسه‌گان unknown-8bit به‌صورت CTE کدگذاری می‌شوند.

fold_binary(name, value)

سرآیند‌ها با استفاده از الگوریتم تا کردن کلاس Header تا زده می‌شوند، که شکستگی‌های خط موجود در مقدار را حفظ می‌کند و هر خط حاصل را متناسب با max_line_length می‌شکند. اگر cte_type برابر 7bit باشد، داده‌های دودویی غیر ASCII به‌صورت CTE و با استفاده از مجموعه‌نویسه‌ی unknown-8bit کدگذاری می‌شوند. در غیر این صورت، سرآیند‌ی منبع اصلی، همراه با شکستگی‌های خط موجود و هرگونه داده‌ی دودویی (نامعتبر از نظر RFC) که ممکن است حاوی آن باشد، استفاده می‌شود.

email.policy.compat32

یک نمونه از Compat32، که سازگاری با عقب را با رفتار بسته‌ی email در Python 3.2 فراهم می‌کند.

توجه

از سیاست compat32 نباید به‌عنوان سیاستی برای اشیاء EmailMessage استفاده شود، و فقط باید برای سریال‌سازی پیام‌هایی استفاده شود که با سیاست compat32 ایجاد شده‌اند.

پانویس‌ها