codecs --- رجیستری کدک و کلاس‌های پایه

کد منبع: Lib/codecs.py

این ماژول کلاس‌های پایه‌ای برای کدک‌های استاندارد پایتون (کدگذارها و کدگشاها) تعریف می‌کند و دسترسی به رجیستری داخلی کدک پایتون را فراهم می‌کند، که فرایند جست‌وجوی کدک و مدیریت خطا را مدیریت می‌کند. بیشتر کدک‌های استاندارد کدگذاری‌های متنی هستند، که متن را به بایت کدگذاری می‌کنند (و بایت را به متن کدگشایی می‌کنند)، اما کدک‌هایی نیز فراهم شده‌اند که متن را به متن و بایت را به بایت کدگذاری می‌کنند. کدک‌های سفارشی می‌توانند میان انواع دلخواه کدگذاری و کدگشایی کنند، اما برخی امکانات ماژول محدود شده‌اند که فقط با کدگذاری‌های متنی یا با کدک‌هایی که به bytes کدگذاری می‌کنند، استفاده شوند.

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

codecs.encode(obj, encoding='utf-8', errors='strict')

obj را با استفاده از کدک ثبت‌شده برای encoding کدگذاری می‌کند.

می‌توان Errors را برای تنظیم طرح‌واره مدیریت خطای مورد نظر مشخص کرد. هندلر پیش‌فرض خطا 'strict' است، به این معنا که خطاهای کدگذاری باعث پرتاب ValueError (یا زیرکلاسی اختصاصی‌تر برای کدک، مانند UnicodeEncodeError) می‌شوند. برای اطلاعات بیشتر درباره مدیریت خطای کدک، به کلاس‌های پایه کدک مراجعه کنید.

codecs.decode(obj, encoding='utf-8', errors='strict')

obj را با استفاده از کدک ثبت‌شده برای encoding کدگشایی می‌کند.

می‌توان Errors را برای تنظیم طرح‌واره مدیریت خطای دلخواه ارائه کرد. هندلر خطای پیش‌فرض 'strict' است، به این معنا که خطاهای کدگشایی باعث پرتاب ValueError (یا یک زیرکلاس خاص‌ترِ مربوط به کدک، مانند UnicodeDecodeError) می‌شوند. برای اطلاعات بیشتر در مورد مدیریت خطای کدک، به کلاس‌های پایه کدک مراجعه کنید.

codecs.charmap_build(string)

یک نگاشت مناسب برای کدگذاری با یک کدگذاری تک‌بایتی سفارشی بازمی‌گرداند. به ازای دریافت یک str string با حداکثر ۲۵۶ نویسه که نشان‌دهنده یک جدول کدگشایی است، یا یک شیء نگاشت داخلی فشرده EncodingMap یا یک دیکشنری برای نگاشت شماره ترتیب هر نویسه به مقادیر بایت بازمی‌گرداند. در صورت ورودی نامعتبر، استثنای TypeError را پرتاب می‌کند.

همچنین می‌توانید جزئیات کامل هر کدک را مستقیماً جستجو کنید:

codecs.lookup(encoding, /)

اطلاعات کدک را در رجیستری کدک‌های پایتون جستجو می‌کند و یک شیء CodecInfo را که در زیر تعریف شده است برمی‌گرداند.

کدگذاری‌ها ابتدا در نهانگاه رجیستری جستجو می‌شوند. اگر یافت نشوند، فهرست توابع جستجوی ثبت‌شده پویش می‌شود. اگر شیء CodecInfo یافت نشود، LookupError پرتاب می‌شود. در غیر این صورت، شیء CodecInfo در نهانگاه ذخیره می‌شود و به فراخواننده برگردانده می‌شود.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

جزئیات کدک هنگام جستجو در رجیستری کدک (codec registry). آرگومان‌های سازنده در ویژگی‌های هم‌نام ذخیره می‌شوند:

name

نام کدگذاری.

encode
decode

توابع کدگذاری و کدگشایی بی‌وضعیت. این‌ها باید توابع یا متدهایی باشند که رابطی یکسان با متدهای encode() و decode() نمونه‌های Codec دارند (به رابط Codec مراجعه کنید). انتظار می‌رود این توابع یا متدها در حالت بی‌وضعیت کار کنند.

incrementalencoder
incrementaldecoder

کلاس‌های کدگذار و کدگشای تدریجی یا توابع کارخانه. این موارد باید به‌ترتیب رابط تعریف‌شده توسط کلاس‌های پایه IncrementalEncoder و IncrementalDecoder را ارائه دهند. کدک‌های تدریجی می‌توانند وضعیت را حفظ کنند.

streamwriter
streamreader

کلاس‌ها یا توابع کارخانه‌ای نویسنده و خواننده جریان. این‌ها باید به‌ترتیب رابط تعریف‌شده توسط کلاس‌های پایه StreamWriter و StreamReader را فراهم کنند. کدک‌های جریان می‌توانند وضعیت را حفظ کنند.

برای ساده‌سازی دسترسی به کامپوننت‌های مختلف کدک، این ماژول این توابع اضافی را فراهم می‌کند که از lookup() برای جست‌وجوی کدک استفاده می‌کنند:

codecs.getencoder(encoding)

کدک مربوط به کدگذاری داده‌شده را جست‌وجو کنید و تابع کدگذار (encoder) آن را برگردانید.

در صورتی که کدگذاری یافت نشود، یک LookupError پرتاب می‌کند.

codecs.getdecoder(encoding)

کدک مربوط به کدگذاری داده‌شده را جست‌وجو می‌کند و تابع کدگشای آن را برمی‌گرداند.

در صورتی که کدگذاری یافت نشود، یک LookupError پرتاب می‌کند.

codecs.getincrementalencoder(encoding)

کدک مربوط به کدگذاری داده‌شده را جستجو می‌کند و کلاس یا تابع کارخانه‌ی کدگذار افزایشی (incremental encoder) آن را بازمی‌گرداند.

در صورتی که کدگذاری یافت نشود یا کدک از کدگذار افزایشی پشتیبانی نکند، استثنای LookupError را پرتاب می‌کند.

codecs.getincrementaldecoder(encoding)

کدک مربوط به کدگذاری داده‌شده را جست‌وجو می‌کند و کلاس یا تابع کارخانه‌ایٔ کدگشای تدریجی آن را برمی‌گرداند.

در صورتی که کدگذاری یافت نشود یا کدک از کدگشای افزایشی پشتیبانی نکند، یک LookupError پرتاب می‌شود.

codecs.getreader(encoding)

کدک مربوط به کدگذاری داده‌شده را جست‌وجو کنید و کلاس StreamReader یا تابع کارخانه‌ای آن را برگردانید.

در صورتی که کدگذاری یافت نشود، یک LookupError پرتاب می‌کند.

codecs.getwriter(encoding)

کدک مربوط به کدگذاری داده‌شده را جستجو کنید و کلاس StreamWriter یا تابع کارخانه (factory function) آن را برگردانید.

در صورتی که کدگذاری یافت نشود، یک LookupError پرتاب می‌کند.

کدک‌های سفارشی با ثبت یک تابع جستجوی کدک مناسب در دسترس قرار می‌گیرند:

codecs.register(search_function, /)

یک تابع جست‌وجوی کدک ثبت کنید. انتظار می‌رود توابع جست‌وجو یک آرگومان دریافت کنند و یک شیء CodecInfo برگردانند؛ این آرگومان نام کدگذاری است که تماماً با حروف کوچک بوده و سطرهای تیره و فاصله‌های آن به زیرخط تبدیل شده‌اند. در صورتی که یک تابع جست‌وجو نتواند کدگذاری داده‌شده را پیدا کند، باید None برگرداند.

تغییر یافته در نسخه‌ی 3.9: خط‌تیره‌ها و فاصله‌ها به زیرخط تبدیل می‌شوند.

codecs.unregister(search_function, /)

یک تابع جست‌وجوی کدک را از ثبت خارج می‌کند و نهانگاه رجیستری را پاک می‌کند. اگر تابع جست‌وجو ثبت‌نشده باشد، کاری انجام نمی‌دهد.

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

اگرچه تابع توکار open() و ماژول مرتبط io رویکرد توصیه‌شده برای کار با پرونده‌های متنی کدگذاری‌شده هستند، این ماژول توابع و کلاس‌های کاربردی اضافی را فراهم می‌کند که امکان استفاده از طیف وسیع‌تری از کدک‌ها را هنگام کار با پرونده‌های دودویی می‌دهند:

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

یک پرونده کدگذاری‌شده را با استفاده از mode داده‌شده باز می‌کند، نمونه‌ای از StreamReaderWriter برمی‌گرداند و کدگذاری/کدگشایی شفاف را فراهم می‌کند. حالت پیش‌فرض پرونده 'r' است، به این معنا که پرونده در حالت خواندن باز می‌شود.

توجه

اگر encoding برابر None نباشد، پرونده‌های کدگذاری‌شده‌ی زیربنایی همیشه در حالت دودویی باز می‌شوند. هیچ تبدیل خودکاری برای '\n' هنگام خواندن و نوشتن انجام نمی‌شود. آرگومان mode می‌تواند هر حالت دودویی قابل‌قبول برای تابع توکار open() باشد؛ 'b' به‌طور خودکار افزوده می‌شود.

encoding کدگذاری مورد استفاده برای پرونده را مشخص می‌کند. هر کدگذاری که به بایت کدگذاری کند و از بایت کدگشایی کند مجاز است، و نوع‌های داده‌ای که متدهای پرونده از آن‌ها پشتیبانی می‌کنند به کدک استفاده‌شده بستگی دارند.

می‌توان errors را برای تعریف مدیریت خطا مشخص کرد. مقدار پیش‌فرض آن 'strict' است که باعث می‌شود در صورت وقوع خطای کدگذاری، یک ValueError پرتاب شود.

buffering همان معنایی را دارد که در تابع توکار open() دارد. مقدار پیش‌فرض آن -1 است، به این معنا که از اندازه پیش‌فرض بافر استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.11: حالت 'U' حذف شده است.

منسوخ شده از نسخه‌ی 3.14: codecs.open() با open() جایگزین شده است.

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

یک نمونه از StreamRecoder برمی‌گرداند، نسخه‌ای پوششی از file که بازکدگذاری شفاف (transcoding) را فراهم می‌کند. پرونده اصلی هنگامی که نسخه پوششی بسته شود، بسته می‌شود.

داده‌های نوشته‌شده در پرونده دربرگرفته‌شده، بر اساس data_encoding داده‌شده کدگشایی می‌شوند و سپس به‌صورت بایت با استفاده از file_encoding در پرونده اصلی نوشته می‌شوند. بایت‌های خوانده‌شده از پرونده اصلی، بر اساس file_encoding کدگشایی می‌شوند و نتیجه با استفاده از data_encoding کدگذاری می‌شود.

اگر file_encoding داده نشود، مقدار پیش‌فرض آن data_encoding خواهد بود.

می‌توان errors را برای تعریف مدیریت خطا مشخص کرد. مقدار پیش‌فرض آن 'strict' است، که باعث می‌شود در صورت بروز خطای کدگذاری، ValueError پرتاب شود.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

از یک کدگذار افزایشی استفاده می‌کند تا ورودی ارائه‌شده توسط iterator را به‌صورت تکراری کدگذاری کند. iterator باید اشیای str را yield کند. این تابع یک تولیدگر است. آرگومان errors (و همچنین هر آرگومان کلیدواژه‌ای دیگر) به کدگذار افزایشی منتقل می‌شود.

این تابع نیاز دارد که کدک، اشیاء متنی str را برای کدگذاری بپذیرد. بنابراین از کدگذارهای بایت‌به‌بایت مانند base64_codec پشتیبانی نمی‌کند.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

از یک کدگشای افزایشی استفاده می‌کند تا ورودی ارائه‌شده توسط iterator را به‌صورت تکراری کدگشایی کند. iterator باید اشیای bytes را تولید کند. این تابع یک تولیدگر است. آرگومان errors (و همچنین هر آرگومان کلیدواژه‌ای دیگر) به کدگشای افزایشی منتقل می‌شود.

این تابع نیاز دارد که کدک اشیای bytes را برای کدگشایی بپذیرد. بنابراین از کدگذارهای متن‌به‌متن مانند rot_13 پشتیبانی نمی‌کند، هرچند می‌توان از rot_13 به‌طور معادل همراه با iterencode() استفاده کرد.

codecs.readbuffer_encode(buffer, errors=None, /)

یک tuple شامل بایت‌های خام buffer، یک شیء سازگار با بافر یا str (که پیش از پردازش به UTF-8 کدگذاری‌شده است)، و طول آن‌ها بر حسب بایت را برمی‌گرداند.

آرگومان errors نادیده گرفته می‌شود.

>>> codecs.readbuffer_encode(b"Zito")
(b'Zito', 4)

این ماژول همچنین ثابت‌های زیر را فراهم می‌کند که برای خواندن و نوشتن در پرونده‌های وابسته به پلتفرم مفید هستند:

codecs.BOM
codecs.BOM_BE
codecs.BOM_LE
codecs.BOM_UTF8
codecs.BOM_UTF16
codecs.BOM_UTF16_BE
codecs.BOM_UTF16_LE
codecs.BOM_UTF32
codecs.BOM_UTF32_BE
codecs.BOM_UTF32_LE

این ثابت‌ها دنباله‌های بایت مختلفی را تعریف می‌کنند که نشانگرهای ترتیب بایت یونیکد (BOM) برای چندین کدگذاری هستند. آن‌ها در جریان‌های داده UTF-16 و UTF-32 برای نشان دادن ترتیب بایت استفاده‌شده و در UTF-8 به‌عنوان امضای یونیکد به کار می‌روند. BOM_UTF16 بسته به ترتیب بایت بومی سکو، BOM_UTF16_BE یا BOM_UTF16_LE است، BOM نام مستعاری برای BOM_UTF16، BOM_LE برای BOM_UTF16_LE و BOM_BE برای BOM_UTF16_BE است. سایر ثابت‌ها نشان‌دهنده‌ی BOM در کدگذاری‌های UTF-8 و UTF-32 هستند.

کلاس‌های پایه کدک

ماژول codecs مجموعه‌ای از کلاس‌های پایه را تعریف می‌کند که رابط‌هایی برای کار با اشیای کدک تعریف می‌کنند و همچنین می‌توانند به‌عنوان مبنایی برای پیاده‌سازی‌های سفارشی کدک استفاده شوند.

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

هندلرهای خطا

برای ساده‌سازی و استانداردسازی مدیریت خطا، ممکن است کدک‌ها روش‌های مختلف مدیریت خطا را با پذیرفتن آرگومان رشته‌ای errors پیاده‌سازی کنند:

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German ß, ♬'

می‌توان از هندلرهای خطای زیر با تمام کدک‌های کدگذاری‌های استاندارد پایتون استفاده کرد:

مقدار

معنی

'strict'

UnicodeError (یا یک زیرکلاس) را پرتاب می‌کند؛ این پیش‌فرض است. در strict_errors() پیاده‌سازی شده است.

'ignore'

داده‌های ناهنجار را نادیده می‌گیرد و بدون اعلان بیشتر ادامه می‌یابد. در ignore_errors() پیاده‌سازی شده است.

'replace'

با یک نشانگر جایگزینی جایگزین می‌شود. هنگام کدگذاری، از ? (نویسه‌ی ASCII) استفاده می‌شود. هنگام کدگشایی، از � (U+FFFD، نویسه جایگزین رسمی) استفاده می‌شود. در replace_errors() پیاده‌سازی شده است.

'backslashreplace'

با دنباله‌های خنثی‌سازی دارای بک‌اسلش جایگزین می‌کند. هنگام کدگذاری، از صورت مبنای شانزده نقطه‌کد یونیکد با قالب‌های \xhh \uxxxx \Uxxxxxxxx استفاده می‌کند. هنگام کدگشایی، از صورت مبنای شانزده مقدار بایت با قالب \xhh استفاده می‌کند. در backslashreplace_errors() پیاده‌سازی شده است.

'surrogateescape'

در کدگشایی، بایت با یک کد جانشین منفرد در بازه‌ی U+DC80 تا U+DCFF جایگزین می‌شود. سپس هرگاه برای کدگذاری داده از هندلر خطای 'surrogateescape' استفاده شود، این کد دوباره به همان بایت تبدیل می‌شود. (برای اطلاعات بیشتر PEP 383 را ببینید.)

هندلرهای خطای زیر فقط برای کدگذاری کاربرد دارند (در کدگذاری‌های متن):

مقدار

معنی

'xmlcharrefreplace'

با ارجاع عددی نویسه XML/HTML جایگزین می‌شود، که نمایش مبنای ده نقطه کد یونیکد با قالب &#num; است. در xmlcharrefreplace_errors() پیاده‌سازی شده است.

'namereplace'

با دنباله‌های خنثی‌سازی \N{...} جایگزین می‌شود؛ آنچه داخل آکولادها قرار دارد، ویژگی Name از پایگاه داده‌ی نویسه‌های یونیکد است. در namereplace_errors() پیاده‌سازی شده است.

علاوه بر این، هندلر خطای زیر مختص کدک‌های داده‌شده است:

مقدار

کدک‌ها

معنی

'surrogatepass'

utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le

اجازه‌ی کدگذاری و کدگشایی نقطه‌کد جانشین (surrogate code point) (U+D800 - U+DFFF) به‌عنوان نقطه‌کد عادی را می‌دهد. در غیر این صورت، این کدک‌ها وجود نقطه‌کد جانشین (surrogate code point) در str را به‌عنوان خطا در نظر می‌گیرند.

اضافه شده در نسخه‌ی 3.1: هندلرهای خطای 'surrogateescape' و 'surrogatepass'.

تغییر یافته در نسخه‌ی 3.4: هندلر خطای 'surrogatepass' اکنون با کدک‌های utf-16* و utf-32* کار می‌کند.

اضافه شده در نسخه‌ی 3.5: هندلر خطای 'namereplace'.

تغییر یافته در نسخه‌ی 3.5: هندلر خطای 'backslashreplace' اکنون با کدگشایی و ترجمه کار می‌کند.

مجموعه‌ی مقادیر مجاز را می‌توان با ثبت یک هندلر خطای نام‌گذاری‌شده جدید گسترش داد:

codecs.register_error(name, error_handler, /)

تابع مدیریت خطای error_handler را با نام name ثبت کنید. آرگومان error_handler در هنگام کدگذاری و کدگشایی در صورت بروز خطا، زمانی که name به‌عنوان پارامتر errors مشخص شده باشد، فراخوانی می‌شود.

در کدگذاری، error_handler با نمونه‌ای از UnicodeEncodeError فراخوانی می‌شود که شامل اطلاعاتی درباره‌ی محل خطا است. هندلر خطا باید یا این استثنا یا استثنای دیگری را پرتاب کند، یا تاپلی برگرداند که شامل جایگزینی برای بخش غیرقابل کدگذاری ورودی و موقعیتی است که کدگذاری باید از آن ادامه یابد. جایگزین می‌تواند str یا bytes باشد. اگر جایگزین bytes باشد، کدگذار به‌سادگی آن‌ها را در بافر خروجی کپی می‌کند. اگر جایگزین یک رشته باشد، کدگذار جایگزین را کدگذاری می‌کند. کدگذاری روی ورودی اصلی در موقعیت مشخص‌شده ادامه می‌یابد. مقادیر منفی موقعیت نسبت به پایان رشته ورودی در نظر گرفته می‌شوند. اگر موقعیت حاصل خارج از محدوده باشد، یک IndexError پرتاب خواهد شد.

کدگشایی و ترجمه به‌صورت مشابه عمل می‌کنند، با این تفاوت که UnicodeDecodeError یا UnicodeTranslateError به هندلر ارسال می‌شود و مقدار جایگزین حاصل از هندلر خطا مستقیماً در خروجی قرار می‌گیرد.

هندلرهای خطای پیش‌تر ثبت‌شده (از جمله هندلرهای خطای استاندارد) را می‌توان با نام جست‌وجو کرد:

codecs.lookup_error(name, /)

هندلر خطایی را که پیش‌تر با نام name ثبت شده است، برمی‌گرداند.

در صورتی که هندلر یافت نشود، استثنای LookupError پرتاب می‌شود.

هندلرهای خطای استاندارد زیر نیز به‌عنوان توابع سطح ماژول در دسترس قرار گرفته‌اند:

codecs.strict_errors(exception)

مدیریت خطای 'strict' را پیاده‌سازی می‌کند.

هر خطای کدگذاری یا کدگشایی یک UnicodeError پرتاب می‌کند.

codecs.ignore_errors(exception)

مدیریت خطای 'ignore' را پیاده‌سازی می‌کند.

داده‌های نامعتبر نادیده گرفته می‌شوند؛ کدگذاری یا کدگشایی بدون اطلاع بیشتر ادامه می‌یابد.

codecs.replace_errors(exception)

مدیریت خطای 'replace' را پیاده‌سازی می‌کند.

در خطاهای کدگذاری، ? (نویسه ASCII) یا در خطاهای کدگشایی، � (U+FFFD، نویسه جایگزین رسمی) را جایگزین می‌کند.

codecs.backslashreplace_errors(exception)

مدیریت خطای 'backslashreplace' را پیاده‌سازی می‌کند.

داده‌های نامعتبر با یک دنباله خنثی‌سازی با بک‌اسلش جایگزین می‌شوند. هنگام کدگذاری، از صورت مبنای شانزدهِ نقطه کد Unicode با قالب‌های \xhh \uxxxx \Uxxxxxxxx استفاده می‌شود. هنگام کدگشایی، از صورت مبنای شانزدهِ مقدار بایت با قالب \xhh استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.5: با کدگشایی و ترجمه کار می‌کند.

codecs.xmlcharrefreplace_errors(exception)

مدیریت خطای 'xmlcharrefreplace' را پیاده‌سازی می‌کند (فقط برای کدگذاری در text encoding).

نویسه‌ی غیرقابل کدگذاری با یک ارجاع عددی نویسه مناسب XML/HTML جایگزین می‌شود، که نمایش مبنای ده نقطه کد یونیکد در قالب &#num; است.

codecs.namereplace_errors(exception)

مدیریت خطای 'namereplace' را پیاده‌سازی می‌کند (فقط برای کدگذاری درون text encoding).

نویسه غیرقابل کدگذاری با یک دنباله‌ی خنثی‌سازی \N{...} جایگزین می‌شود. مجموعه‌ی نویسه‌هایی که بین آکولادها قرار دارند، ویژگی Name از پایگاه داده‌ی نویسه‌های یونیکد (Unicode Character Database) است. برای مثال، حرف کوچک آلمانی 'ß' به دنباله‌ی بایت \N{LATIN SMALL LETTER SHARP S} تبدیل می‌شود.

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

کدگذاری و کدگشایی بی‌وضعیت

کلاس پایه‌ی Codec این متدها را تعریف می‌کند که رابط‌های تابعی کدگذار و کدگشای بی‌وضعیت را نیز تعریف می‌کنند:

class codecs.Codec
encode(input, errors='strict')

شیء input را کدگذاری می‌کند و یک تاپل (شیء خروجی، طول مصرف‌شده) برمی‌گرداند. برای مثال، کدگذاری متن یک شیء رشته را با استفاده از یک کدگذاری مجموعه نویسه خاص به یک شیء bytes تبدیل می‌کند (مثلاً cp1252 یا iso-8859-1).

آرگومان errors مدیریت خطای قابل اعمال را تعریف می‌کند. مقدار پیش‌فرض آن مدیریت 'strict' است.

این متد نباید وضعیت را در نمونه‌ی Codec ذخیره کند. برای کدک‌هایی که باید وضعیت را به‌منظور کارآمد کردن کدگذاری حفظ کنند، از StreamWriter استفاده کنید.

کدگذار باید بتواند ورودی با طول صفر را مدیریت کند و در این شرایط، یک شیء خالی از نوع شیء خروجی را برگرداند.

decode(input, errors='strict')

شیء input را کدگشایی می‌کند و یک تاپل (شیء خروجی، طول مصرف‌شده) را برمی‌گرداند. برای مثال، برای یک کدگذاری متن، کدگشایی یک شیء bytes را که با استفاده از یک کدگذاری مجموعه نویسه خاص کدگذاری شده است، به یک شیء رشته تبدیل می‌کند.

برای کدگذاری‌های متنی و کدک‌های بایت‌به‌بایت (bytes-to-bytes)، input باید یک شیء bytes یا شیء‌ای باشد که رابط بافر فقط‌خواندنی را فراهم می‌کند -- برای مثال، اشیای بافر و پرونده‌های نگاشت‌شده به حافظه.

آرگومان errors مدیریت خطای قابل اعمال را تعریف می‌کند. مقدار پیش‌فرض آن مدیریت 'strict' است.

این متد نباید وضعیت را در نمونه‌ی Codec ذخیره کند. برای کدک‌هایی که باید برای کارآمد کردن کدگشایی وضعیت را نگه دارند، از StreamReader استفاده کنید.

کدگشا باید بتواند ورودی با طول صفر را مدیریت کند و در این شرایط، یک شیء خالی از نوع شیء خروجی را برگرداند.

کدگذاری و کدگشایی تدریجی

کلاس‌های IncrementalEncoder و IncrementalDecoder رابط پایه را برای کدگذاری و کدگشایی افزایشی فراهم می‌کنند. کدگذاری/کدگشایی ورودی با یک فراخوانی تابع کدگذار/کدگشای بدون وضعیت انجام نمی‌شود، بلکه با چندین فراخوانی متد encode()/decode() از کدگذار/کدگشای افزایشی انجام می‌شود. کدگذار/کدگشای افزایشی فرایند کدگذاری/کدگشایی را در طول فراخوانی‌های متد پیگیری می‌کند.

خروجی به‌هم‌پیوسته‌ی فراخوانی‌های متد encode()/decode() همان است که گویی همه‌ی ورودی‌های منفرد به یک ورودی پیوسته شده باشند و این ورودی با کدگذار/کدگشای بی‌وضعیت کدگذاری/کدگشایی شده باشد.

اشیاء IncrementalEncoder

کلاس IncrementalEncoder برای کدگذاری یک ورودی در چندین مرحله استفاده می‌شود. این کلاس متدهای زیر را تعریف می‌کند که هر کدگذار افزایشی باید برای سازگاری با رجیستری کدک پایتون (Python codec registry) آن‌ها را تعریف کند.

class codecs.IncrementalEncoder(errors='strict')

سازنده برای یک نمونه از IncrementalEncoder.

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

IncrementalEncoder می‌تواند با ارائه‌ی آرگومان کلیدواژه‌ای errors، روش‌های مختلف مدیریت خطا را پیاده‌سازی کند. برای مقادیر ممکن، هندلرهای خطا را ببینید.

آرگومان errors به یک ویژگی هم‌نام اختصاص داده می‌شود. اختصاص دادن به این ویژگی، امکان جابه‌جایی بین راهبردهای مختلف مدیریت خطا را در طول عمر شیء IncrementalEncoder فراهم می‌کند.

encode(object, final=False)

object را کدگذاری می‌کند (با در نظر گرفتن وضعیت فعلی کدگذار) و شیء کدگذاری‌شده‌ی حاصل را بازمی‌گرداند. اگر این آخرین فراخوانی encode() باشد، final باید true باشد (پیش‌فرض false است).

reset()

کدگذار را به وضعیت اولیه بازنشانی کنید. خروجی دور ریخته می‌شود: .encode(object, final=True) را فراخوانی کنید و در صورت نیاز، یک رشته بایتی یا متنی خالی را ارسال کنید تا کدگذار بازنشانی شود و خروجی دریافت شود.

getstate()

وضعیت فعلی کدگذار را برمی‌گرداند که باید یک عدد صحیح باشد. پیاده‌سازی باید اطمینان حاصل کند که 0 رایج‌ترین وضعیت است. (وضعیت‌هایی که از اعداد صحیح پیچیده‌تر هستند، می‌توانند با مارشال/پیکل کردن (marshaling/pickling) وضعیت و کدگذاری بایت‌های رشته حاصل به یک عدد صحیح تبدیل شوند.)

setstate(state)

وضعیت کدگذار را روی state تنظیم کنید. state باید یک وضعیت کدگذار باشد که توسط getstate() برگردانده شده است.

اشیاء IncrementalDecoder

کلاس IncrementalDecoder برای کدگشایی یک ورودی در چند مرحله استفاده می‌شود. این کلاس متدهای زیر را تعریف می‌کند که هر کدگشای افزایشی باید برای سازگاری با رجیستری کدک پایتون (Python codec registry) آن‌ها را تعریف کند.

class codecs.IncrementalDecoder(errors='strict')

سازنده‌ی یک نمونه از IncrementalDecoder.

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

IncrementalDecoder می‌تواند با ارائه آرگومان کلیدواژه‌ای errors، روش‌های مختلف مدیریت خطا را پیاده‌سازی کند. برای مقادیر ممکن، هندلرهای خطا را ببینید.

آرگومان errors به ویژگی‌ای با همین نام اختصاص داده می‌شود. اختصاص دادن به این ویژگی امکان جابه‌جایی بین راهبردهای مختلف مدیریت خطا را در طول عمر شیء IncrementalDecoder فراهم می‌کند.

decode(object, final=False)

object را کدگشایی می‌کند (وضعیت فعلی کدگشا را در نظر می‌گیرد) و شیء کدگشایی‌شده‌ی حاصل را برمی‌گرداند. اگر این آخرین فراخوانی decode() باشد، final باید true باشد (پیش‌فرض false است). اگر final برابر true باشد، کدگشا باید ورودی را به‌طور کامل کدگشایی کند و تمام بافرها را تخلیه کند. اگر این کار ممکن نباشد (مثلاً به دلیل دنباله‌های ناقص بایت در پایان ورودی)، باید مدیریت خطا را دقیقاً مانند حالت بی‌وضعیت (stateless) آغاز کند (که ممکن است استثنایی را پرتاب کند).

reset()

کدگشا را به وضعیت اولیه بازنشانی کنید.

getstate()

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

setstate(state)

وضعیت کدگشا را روی state تنظیم کنید. state باید یک وضعیت کدگشا باشد که getstate() آن را برمی‌گرداند.

کدگذاری و کدگشایی جریان

کلاس‌های StreamWriter و StreamReader رابط‌های کاری عامی فراهم می‌کنند که می‌توان از آن‌ها برای پیاده‌سازی زیرماژول‌های جدید کدگذاری به‌صورت بسیار آسان استفاده کرد. برای مشاهده نمونه‌ای از چگونگی انجام این کار، encodings.utf_8 را ببینید.

اشیای StreamWriter

کلاس StreamWriter یک زیرکلاس از Codec است و متدهای زیر را تعریف می‌کند که هر نویسنده‌ی جریان (stream writer) باید آن‌ها را تعریف کند تا با رجیستری کدک پایتون (Python codec registry) سازگار باشد.

class codecs.StreamWriter(stream, errors='strict')

سازنده برای یک نمونه از StreamWriter.

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

آرگومان stream باید یک شیء شبه‌پرونده باشد که برای نوشتن متن یا داده‌های دودویی، متناسب با کدک مشخص، باز شده باشد.

StreamWriter می‌تواند با ارائه آرگومان کلیدواژه‌ای errors، روش‌های مختلفی برای مدیریت خطا را پیاده‌سازی کند. برای هندلرهای خطای استانداردی که کدک جریان زیرین ممکن است از آن‌ها پشتیبانی کند، هندلرهای خطا را ببینید.

آرگومان errors به ویژگی‌ای به همین نام منتسب می‌شود. انتساب به این ویژگی امکان جابه‌جایی بین شیوه‌های مختلف مدیریت خطا را در طول عمر شیء StreamWriter فراهم می‌کند.

write(object)

محتوای شیء را به‌صورت کدگذاری‌شده در جریان می‌نویسد.

writelines(list)

رشته‌های به‌هم‌پیوسته‌ی یک پیمایش‌پذیر را در جریان می‌نویسد (احتمالاً با استفاده‌ی مجدد از متد write()). پیمایش‌پذیرهای بی‌نهایت یا بسیار بزرگ پشتیبانی نمی‌شوند. کدک‌های استاندارد بایت-به-بایت از این متد پشتیبانی نمی‌کنند.

reset()

بافرهای کدک را که برای نگه‌داری وضعیت داخلی به کار می‌روند، بازنشانی می‌کند.

فراخوانی این متد باید تضمین کند که داده‌های خروجی در وضعیت پاکی قرار می‌گیرند، به‌گونه‌ای که افزودن داده‌های تازه بدون نیاز به بازبینی مجدد کل جریان برای بازیابی وضعیت ممکن باشد.

علاوه بر متدهای فوق، StreamWriter همچنین باید تمام متدها و ویژگی‌های دیگر را از جریان زیرین به ارث ببرد.

اشیاء StreamReader

کلاس StreamReader زیرکلاسی از Codec است و متدهای زیر را تعریف می‌کند که هر خواننده جریانی (stream reader) باید آن‌ها را تعریف کند تا با رجیستری کدک پایتون (Python codec registry) سازگار باشد.

class codecs.StreamReader(stream, errors='strict')

سازنده‌ای برای یک نمونه از StreamReader.

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

آرگومان stream باید یک شیء شبه‌پرونده باشد که برای خواندن متن یا داده‌ی دودویی، متناسب با کدک مشخص، باز باشد.

StreamReader ممکن است با ارائه آرگومان کلیدواژه‌ای errors، روش‌های مختلف مدیریت خطا را پیاده‌سازی کند. برای آشنایی با هندلرهای خطای استانداردی که کدک جریان زیرین ممکن است پشتیبانی کند، هندلرهای خطا را ببینید.

آرگومان errors به ویژگی‌ای با همین نام اختصاص داده می‌شود. انتساب به این ویژگی امکان جابه‌جایی بین راهبردهای مختلف مدیریت خطا را در طول عمر شیء StreamReader فراهم می‌کند.

مجموعه مقادیر مجاز برای آرگومان errors را می‌توان با register_error() گسترش داد.

read(size=-1, chars=-1, firstline=False)

داده را از جریان کدگشایی می‌کند و شیء حاصل را برمی‌گرداند.

آرگومان chars تعداد نقاط کد کدگشایی‌شده یا بایت‌هایی را که باید بازگردانده شوند، نشان می‌دهد. متد read() هرگز داده‌ای بیشتر از مقدار درخواست‌شده برنمی‌گرداند، اما ممکن است در صورتی که به اندازه کافی داده در دسترس نباشد، کمتر برگرداند.

آرگومان size نشان‌دهنده‌ی حداکثر تعداد تقریبی بایت‌های کدگذاری‌شده یا نقاط کدی است که برای کدگشایی خوانده می‌شوند. کدگشا می‌تواند این تنظیم را به‌صورت مناسب تغییر دهد. مقدار پیش‌فرض -1 نشان می‌دهد که تا حد امکان خوانده و کدگشایی شود. این پارامتر برای جلوگیری از نیاز به کدگشایی پرونده‌های بسیار بزرگ در یک مرحله در نظر گرفته شده است.

پرچم firstline نشان می‌دهد که اگر در سطرهای بعدی خطاهای کدگشایی وجود داشته باشد، برگرداندن تنها خط اول کافی است.

این متد باید از یک راهبرد خواندن حریصانه استفاده کند، به این معنا که باید هر مقدار داده‌ای را که در چارچوب تعریف کدگذاری و اندازه‌ی داده‌شده مجاز است بخواند؛ برای مثال، اگر پایان‌های اختیاری کدگذاری یا نشانگرهای وضعیت در جریان در دسترس باشند، آن‌ها نیز باید خوانده شوند.

readline(size=None, keepends=True)

یک خط از جریان ورودی می‌خواند و داده کدگشایی‌شده را برمی‌گرداند.

size، در صورت ارائه، به‌عنوان آرگومان size به متد read() جریان ارسال می‌شود.

اگر keepends نادرست باشد، پایان‌سطرها از سطرهای برگردانده‌شده حذف می‌شوند.

readlines(sizehint=None, keepends=True)

تمام سطرهای موجود در جریان ورودی را می‌خواند و آن‌ها را به‌صورت فهرستی از سطرها برمی‌گرداند.

پایان سطرها با استفاده از متد decode() کدک پیاده‌سازی می‌شوند و در صورتی که keepends درست باشد، در آیتم‌های فهرست گنجانده می‌شوند.

sizehint، در صورت داده شدن، به‌عنوان آرگومان size به متد read() جریان ارسال می‌شود.

reset()

بافرهای کدک را که برای نگه‌داری وضعیت داخلی به کار می‌روند، بازنشانی می‌کند.

توجه داشته باشید که هیچ‌گونه جابه‌جایی جریان نباید انجام شود. این متد عمدتاً برای امکان بازیابی از خطاهای کدگشایی در نظر گرفته شده است.

علاوه بر متدهای فوق، StreamReader باید تمام متدها و ویژگی‌های دیگر را نیز از جریان زیرین به ارث ببرد.

اشیای StreamReaderWriter

StreamReaderWriter کلاسی سهولت‌بخش است که به شما امکان می‌دهد جریان‌هایی را که در هر دو حالت خواندن و نوشتن کار می‌کنند، پوشش دهید.

طراحی به گونه‌ای است که می‌توان از توابع کارخانه‌ای که توسط تابع lookup() برگردانده می‌شوند، برای ساخت نمونه استفاده کرد.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

یک نمونه از StreamReaderWriter ایجاد می‌کند. stream باید یک شیء شبه‌پرونده باشد. Reader و Writer باید توابع کارخانه‌ای یا کلاس‌هایی باشند که به‌ترتیب رابط‌های StreamReader و StreamWriter را ارائه می‌دهند. مدیریت خطا به همان روشی انجام می‌شود که برای خواننده‌ها و نویسنده‌های جریان تعریف شده است.

نمونه‌های StreamReaderWriter رابط‌های ترکیب‌شده‌ی کلاس‌های StreamReader و StreamWriter را تعریف می‌کنند. آن‌ها تمام متدها و ویژگی‌های دیگر را از جریان زیربنایی به ارث می‌برند.

اشیاء StreamRecoder

StreamRecoder داده‌ها را از یک کدگذاری به کدگذاری دیگر تبدیل می‌کند، که گاهی هنگام کار با محیط‌های کدگذاری مختلف مفید است.

طراحی به گونه‌ای است که می‌توان از توابع کارخانه‌ای که توسط تابع lookup() برگردانده می‌شوند، برای ساخت نمونه استفاده کرد.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

نمونه‌ای از StreamRecoder می‌سازد که یک تبدیل دوطرفه را پیاده‌سازی می‌کند: encode و decode در بخش جلویی (frontend) کار می‌کنند — داده‌هایی که برای کدی که read() و write() را فراخوانی می‌کند قابل مشاهده است، در حالی که Reader و Writer در بخش بک‌اند کار می‌کنند — داده‌های موجود در stream.

می‌توانید از این شیء‌ها برای انجام بازکدگذاری‌های شفاف (transcoding) استفاده کنید، برای مثال از Latin-1 به UTF-8 و برعکس.

آرگومان stream باید یک شیء شبه‌پرونده باشد.

آرگومان‌های encode و decode باید از رابط Codec پیروی کنند. Reader و Writer باید توابع یا کلاس‌های کارخانه‌ای باشند که به‌ترتیب شیءهایی از رابط‌های StreamReader و StreamWriter فراهم می‌کنند.

مدیریت خطا به همان شیوه‌ای انجام می‌شود که برای خواننده‌ها و نویسنده‌های استریم تعریف شده است.

نمونه‌های StreamRecoder رابط‌های ترکیبی کلاس‌های StreamReader و StreamWriter را تعریف می‌کنند. آن‌ها تمام متدها و ویژگی‌های دیگر را از جریان زیربنایی به ارث می‌برند.

کدگذاری‌ها و یونیکد

رشته‌ها به‌صورت داخلی به‌عنوان دنباله‌هایی از نقاط کد (code points) در بازه‌ی U+0000--U+10FFFF ذخیره می‌شوند. (برای جزئیات بیشتر درباره‌ی پیاده‌سازی، PEP 393 را ببینید.) هنگامی که از یک شیء رشته خارج از پردازنده و حافظه استفاده شود، ترتیب بایت‌ها (endianness) و چگونگی ذخیره‌ی این آرایه‌ها به‌صورت بایت به یک مسئله تبدیل می‌شوند. مانند سایر کدک‌ها، سریال‌سازی (serialising) یک رشته به دنباله‌ای از بایت‌ها به‌عنوان کدگذاری شناخته می‌شود، و بازسازی رشته از دنباله‌ای از بایت‌ها به‌عنوان کدگشایی شناخته می‌شود. کدک‌های سریال‌سازی متن گوناگونی وجود دارند که جمعاً به‌عنوان کدگذاری‌های متنی شناخته می‌شوند.

ساده‌ترین کدگذاری متن (که 'latin-1' یا 'iso-8859-1' نامیده می‌شود) نقاط کد ۰ تا ۲۵۵ را به بایت‌های 0x0 تا 0xff نگاشت می‌کند؛ این بدان معناست که شیء رشته‌ای که شامل نقاط کد بالاتر از U+00FF باشد، با این کدک قابل کدگذاری نیست. این کار باعث پرتاب یک UnicodeEncodeError می‌شود که به شکل زیر است (اگرچه ممکن است جزئیات پیام خطا متفاوت باشد): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256).

گروه دیگری از کدگذاری‌ها (کدگذاری‌های به‌اصطلاح charmap) وجود دارند که زیرمجموعه‌ای متفاوت از همه نقاط کد یونیکد و چگونگی نگاشت این نقاط کد به بایت‌های 0x0--0xff را انتخاب می‌کنند. برای دیدن اینکه این کار چگونه انجام می‌شود، کافی است برای مثال encodings/cp1252.py را باز کنید (که کدگذاری‌ای است که عمدتاً در ویندوز به کار می‌رود). یک ثابت رشته‌ای شامل ۲۵۶ نویسه وجود دارد که به شما نشان می‌دهد کدام نویسه به کدام مقدار بایت نگاشته شده است.

تمام این کدگذاری‌ها تنها می‌توانند ۲۵۶ نقطه‌کد از میان ۱۱۱۴۱۱۲ نقطه‌کد تعریف‌شده در یونیکد را کدگذاری کنند. یک راه ساده و مستقیم که می‌تواند هر نقطه‌کد یونیکد را ذخیره کند، این است که هر نقطه‌کد به‌صورت چهار بایت متوالی ذخیره شود. دو حالت وجود دارد: بایت‌ها به ترتیب بزرگ‌اندیان (big endian) یا کوچک‌اندیان (little endian) ذخیره شوند. به این دو کدگذاری به‌ترتیب UTF-32-BE و UTF-32-LE گفته می‌شود. عیب آن‌ها این است که اگر، برای مثال، از UTF-32-BE روی یک ماشین کوچک‌اندیان استفاده کنید، همیشه باید بایت‌ها را در کدگذاری و کدگشایی جابه‌جا کنید. کدک‌های UTF-16 و UTF-32 پایتون با استفاده از ترتیب بایت بومی سکو در صورت نبود BOM، از این مشکل اجتناب می‌کنند. پایتون از رویه‌ی رایج سکو پیروی می‌کند، بنابراین رفت‌وبرگشت داده‌های با ترتیب بایت بومی بدون جابه‌جایی اضافی بایت‌ها انجام می‌شود، هرچند استاندارد یونیکد در صورت مشخص نبودن ترتیب بایت‌ها، به‌طور پیش‌فرض از بزرگ‌اندیان استفاده می‌کند. هنگامی که این بایت‌ها توسط یک CPU با ترتیب بایت متفاوت خوانده شوند، باید بایت‌ها جابه‌جا شوند. برای تشخیص ترتیب بایت یک دنباله‌ی بایتی UTF-16 یا UTF-32، از BOM («نشانگر ترتیب بایت») استفاده می‌شود. این نویسه‌ی یونیکد U+FEFF است. این نویسه می‌تواند به ابتدای هر دنباله‌ی بایتی UTF-16 یا UTF-32 افزوده شود. نسخه‌ی جابه‌جاشده‌ی بایت‌های این نویسه (0xFFFE) یک نویسه‌ی غیرمجاز است که نباید در متن یونیکد ظاهر شود. هنگامی که اولین نویسه‌ی یک دنباله‌ی بایتی UTF-16 یا UTF-32 برابر U+FFFE باشد، باید بایت‌ها در کدگشایی جابه‌جا شوند.

متأسفانه نویسه‌ی U+FEFF کاربرد دومی به‌عنوان ZERO WIDTH NO-BREAK SPACE داشت: نویسه‌ای که عرضی ندارد و اجازه نمی‌دهد یک واژه شکسته شود. برای مثال، می‌توان از آن برای دادن سرنخ‌هایی به یک الگوریتم لیگاتور (ligature) استفاده کرد. از یونیکد 4.0، استفاده از U+FEFF به‌عنوان ZERO WIDTH NO-BREAK SPACE منسوخ شده است (و U+2060 (WORD JOINER) این نقش را بر عهده گرفته است). با این حال، نرم‌افزارهای یونیکد همچنان باید بتوانند U+FEFF را در هر دو نقش پردازش کنند: در نقش BOM، ابزاری است برای تعیین چیدمان ذخیره‌سازی بایت‌های کدگذاری‌شده، و پس از اینکه دنباله‌ی بایت‌ها به یک رشته کدگشایی شد، ناپدید می‌شود؛ در نقش ZERO WIDTH NO-BREAK SPACE، نویسه‌ای عادی است که مانند هر نویسه‌ی دیگری کدگشایی خواهد شد.

کدگذاری دیگری نیز وجود دارد که می‌تواند تمام بازه‌ی نویسه‌های یونیکد را کدگذاری کند: UTF-8. UTF-8 یک کدگذاری ۸ بیتی است، به این معنا که در UTF-8 هیچ مشکلی از بابت ترتیب بایت‌ها وجود ندارد. هر بایت در یک دنباله‌ی بایتی UTF-8 از دو بخش تشکیل شده است: بیت‌های نشانگر (بیت‌های پرارزش) و بیت‌های بار. بیت‌های نشانگر دنباله‌ای از صفر تا چهار بیت 1 هستند که پس از آن‌ها یک بیت 0 می‌آید. نویسه‌های یونیکد به این صورت کدگذاری می‌شوند (که در آن x نشان‌دهنده‌ی بیت‌های بار است و با الحاق آن‌ها، نویسه‌ی یونیکد به دست می‌آید):

بازه

کدگذاری

U-00000000 ... U-0000007F

0xxxxxxx

U-00000080 ... U-000007FF

110xxxxx 10xxxxxx

U-00000800 ... U-0000FFFF

1110xxxx 10xxxxxx 10xxxxxx

U-00010000 ... U-0010FFFF

11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

کم‌ارزش‌ترین بیت نویسه‌ی یونیکد، راست‌ترین بیت x است.

از آن‌جا که UTF-8 یک کدگذاری ۸-بیتی است، نیازی به نشانگر ترتیب بایت‌ها (BOM) نیست و هر نویسه‌ی U+FEFF در رشته‌ی کدگشایی‌شده (حتی اگر اولین نویسه باشد) به‌عنوان یک ZERO WIDTH NO-BREAK SPACE در نظر گرفته می‌شود.

بدون اطلاعات خارجی، نمی‌توان به‌طور قابل‌اطمینان تعیین کرد کدام کدگذاری برای کدگذاری یک رشته استفاده شده است. هر کدگذاری charmap می‌تواند هر دنباله بایت تصادفی را کدگشایی کند. اما این موضوع در مورد UTF-8 ممکن نیست، زیرا دنباله‌های بایت UTF-8 دارای ساختاری هستند که دنباله‌های بایت دلخواه را مجاز نمی‌داند. برای افزایش قابلیت اطمینانی که می‌توان با آن کدگذاری UTF-8 را تشخیص داد، مایکروسافت برای برنامه Notepad خود گونه‌ای از UTF-8 را ابداع کرد (که پایتون آن را "utf-8-sig" می‌نامد): پیش از آنکه هر یک از نویسه‌های Unicode به پرونده نوشته شود، یک BOM کدگذاری‌شده با UTF-8 (که به‌صورت یک دنباله بایت به این شکل به نظر می‌رسد: 0xef، 0xbb، 0xbf) نوشته می‌شود. از آنجا که نسبتاً بعید است هیچ پرونده کدگذاری‌شده با charmap با این مقادیر بایت شروع شود (که برای مثال نگاشت می‌شوند به

نویسه‌ی کوچک لاتین I با دونقطه (DIAERESIS)
علامت نقل‌قول زاویه‌ای دوتایی رو به راست
علامت سؤال وارونه

در iso-8859-1)، این موضوع احتمال اینکه کدگذاری utf-8-sig بتواند به‌درستی از روی دنباله‌ی بایت‌ها حدس زده شود را افزایش می‌دهد. بنابراین در اینجا نشانه‌ی ترتیب بایت‌ها (BOM) برای تعیین ترتیب بایت‌های استفاده‌شده برای تولید دنباله‌ی بایت‌ها استفاده نمی‌شود، بلکه به‌عنوان امضایی است که به حدس زدن کدگذاری کمک می‌کند. هنگام کدگذاری، کدک utf-8-sig 0xef، 0xbb و 0xbf را به‌عنوان سه بایت نخست در پرونده می‌نویسد. هنگام کدگشایی، utf-8-sig آن سه بایت را در صورتی که به‌عنوان سه بایت نخست در پرونده ظاهر شوند، نادیده می‌گیرد. در UTF-8، استفاده از BOM توصیه نمی‌شود و عموماً باید از آن اجتناب شود.

کدگذاری‌های استاندارد

پایتون همراه با تعدادی کدک توکار است که یا به‌صورت توابع C یا با استفاده از دیکشنری‌ها به‌عنوان جداول نگاشت پیاده‌سازی شده‌اند. جدول زیر کدک‌ها را بر اساس نام، به‌همراه چند نام مستعار رایج و زبان‌هایی که احتمالاً کدگذاری برای آن‌ها استفاده می‌شود، فهرست می‌کند. هیچ‌یک از فهرست نام‌های مستعار و فهرست زبان‌ها برای جامع بودن در نظر گرفته نشده است. توجه داشته باشید که نوشتارهای جایگزینی که فقط از نظر بزرگی یا کوچکی حروف تفاوت دارند یا به‌جای زیرخط از خط تیره استفاده می‌کنند نیز نام‌های مستعار معتبر هستند، زیرا وقتی با normalize_encoding() نرمال‌سازی شوند، معادل یکدیگر هستند. برای مثال، 'utf-8' یک نام مستعار معتبر برای کدک 'utf_8' است.

توجه

جدول زیر رایج‌ترین نام‌های مستعار را فهرست می‌کند، برای فهرست کامل به پرونده منبع aliases.py مراجعه کنید.

در ویندوز، کدک‌های cpXXX برای تمام صفحه‌های کد در دسترس هستند. اما تضمین می‌شود که تنها کدک‌های فهرست‌شده در جدول زیر در سایر پلتفرم‌ها وجود داشته باشند.

برخی کدگذاری‌های رایج می‌توانند برای بهبود کارایی، سازوکار جست‌وجوی کدک‌ها را دور بزنند. این فرصت‌های بهینه‌سازی تنها برای مجموعه‌ای محدود از نام‌های مستعار (غیرحساس به بزرگی و کوچکی حروف) توسط CPython شناسایی می‌شوند: utf-8، utf8، latin-1، latin1، iso-8859-1، iso8859-1، mbcs (فقط ویندوز)، ascii، us-ascii، utf-16، utf16، utf-32، utf32، و همان موارد با استفاده از زیرسطرها به‌جای سطرهای تیره. استفاده از نام‌های مستعار جایگزین برای این کدگذاری‌ها ممکن است باعث اجرای کندتر شود.

تغییر یافته در نسخه‌ی 3.6: فرصت بهینه‌سازی برای us-ascii شناسایی شد.

بسیاری از مجموعه‌نویسه‌ها از زبان‌های یکسانی پشتیبانی می‌کنند. آن‌ها از نظر نویسه‌های منفرد (مثلاً اینکه آیا EURO SIGN پشتیبانی می‌شود یا نه) و از نظر تخصیص نویسه‌ها به موقعیت‌های کد تفاوت دارند. به‌ویژه برای زبان‌های اروپایی، معمولاً گونه‌های زیر وجود دارند:

  • یک مجموعه‌کد ISO 8859

  • یک صفحه کد (code page) مایکروسافت ویندوز، که به‌طور معمول از یک مجموعه کد (codeset) 8859 مشتق شده است، اما نویسه‌های کنترلی را با نویسه‌های گرافیکی اضافی جایگزین می‌کند

  • یک صفحه‌کد IBM EBCDIC

  • یک صفحه‌کد IBM PC که با ASCII سازگار است

کدک

نام‌های مستعار

زبان‌ها

ascii

646, us-ascii

انگلیسی

big5

big5-tw, csbig5

چینی سنتی

big5hkscs

big5-hkscs, hkscs

چینی سنتی

cp037

IBM037, IBM039

انگلیسی

cp273

273, IBM273, csIBM273

آلمانی

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

cp424

EBCDIC-CP-HE, IBM424

عبری

cp437

437, IBM437

انگلیسی

cp500

EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500

اروپای غربی

cp720

عربی

cp737

یونانی

cp775

IBM775

زبان‌های بالتیک

cp850

850, IBM850

اروپای غربی

cp852

852, IBM852

اروپای مرکزی و شرقی

cp855

855, IBM855

بلاروسی، بلغاری، مقدونی، روسی، صربی

cp856

عبری

cp857

857, IBM857

ترکی

cp858

858, IBM00858

اروپای غربی

cp860

860, IBM860

پرتغالی

cp861

861, CP-IS, IBM861

ایسلندی

cp862

862, IBM862

عبری

cp863

863, IBM863

کانادایی

cp864

IBM864

عربی

cp865

865, IBM865

دانمارکی، نروژی

cp866

866, IBM866

روسی

cp869

869, CP-GR, IBM869

یونانی

cp874

تایلندی

cp875

یونانی

cp932

932, ms932, mskanji, ms-kanji, windows-31j

ژاپنی

cp949

949, ms949, uhc

کره‌ای

cp950

950, ms950

چینی سنتی

cp1006

اردو

cp1026

ibm1026

ترکی

cp1125

1125, ibm1125, cp866u, ruscii

اوکراینی

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

cp1140

IBM01140

اروپای غربی

cp1250

windows-1250

اروپای مرکزی و شرقی

cp1251

windows-1251

بلاروسی، بلغاری، مقدونی، روسی، صربی

cp1252

windows-1252

اروپای غربی

cp1253

windows-1253

یونانی

cp1254

windows-1254

ترکی

cp1255

windows-1255

عبری

cp1256

windows-1256

عربی

cp1257

windows-1257

زبان‌های بالتیک

cp1258

windows-1258

ویتنامی

euc_jp

eucjp, ujis, u-jis

ژاپنی

euc_jis_2004

jisx0213, eucjis2004

ژاپنی

euc_jisx0213

eucjisx0213

ژاپنی

euc_kr

euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001

کره‌ای

gb2312

chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58

چینی ساده‌شده

gbk

936, cp936, ms936

چینی یک‌پارچه

gb18030

gb18030-2000

چینی یک‌پارچه

hz

hzgb, hz-gb, hz-gb-2312

چینی ساده‌شده

iso2022_jp

csiso2022jp, iso2022jp, iso-2022-jp

ژاپنی

iso2022_jp_1

iso2022jp-1, iso-2022-jp-1

ژاپنی

iso2022_jp_2

iso2022jp-2, iso-2022-jp-2

ژاپنی، کره‌ای، چینی ساده‌شده، اروپای غربی، یونانی

iso2022_jp_2004

iso2022jp-2004, iso-2022-jp-2004

ژاپنی

iso2022_jp_3

iso2022jp-3, iso-2022-jp-3

ژاپنی

iso2022_jp_ext

iso2022jp-ext, iso-2022-jp-ext

ژاپنی

iso2022_kr

csiso2022kr, iso2022kr, iso-2022-kr

کره‌ای

latin_1

iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1

اروپای غربی

iso8859_2

iso-8859-2, latin2, L2

اروپای مرکزی و شرقی

iso8859_3

iso-8859-3, latin3, L3

اسپرانتو، مالتی

iso8859_4

iso-8859-4, latin4, L4

اروپای شمالی

iso8859_5

iso-8859-5, cyrillic

بلاروسی، بلغاری، مقدونی، روسی، صربی

iso8859_6

iso-8859-6, arabic

عربی

iso8859_7

iso-8859-7, greek, greek8

یونانی

iso8859_8

iso-8859-8, hebrew

عبری

iso8859_9

iso-8859-9, latin5, L5

ترکی

iso8859_10

iso-8859-10, latin6, L6

زبان‌های نوردیک

iso8859_11

iso-8859-11, thai

زبان‌های تایلندی

iso8859_13

iso-8859-13, latin7, L7

زبان‌های بالتیک

iso8859_14

iso-8859-14, latin8, L8

زبان‌های سلتی

iso8859_15

iso-8859-15, latin9, L9

اروپای غربی

iso8859_16

iso-8859-16, latin10, L10

جنوب شرقی اروپا

johab

cp1361, ms1361

کره‌ای

koi8_r

روسی

koi8_t

تاجیکی

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

koi8_u

اوکراینی

kz1048

kz_1048, strk1048_2002, rk1048

قزاقی

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

mac_cyrillic

maccyrillic

بلاروسی، بلغاری، مقدونی، روسی، صربی

mac_greek

macgreek

یونانی

mac_iceland

maciceland

ایسلندی

mac_latin2

maclatin2, maccentraleurope, mac_centeuro

اروپای مرکزی و شرقی

mac_roman

macroman, macintosh

اروپای غربی

mac_turkish

macturkish

ترکی

ptcp154

csptcp154, pt154, cp154, cyrillic-asian

قزاقی

shift_jis

csshiftjis, shiftjis, sjis, s_jis

ژاپنی

shift_jis_2004

shiftjis2004, sjis_2004, sjis2004

ژاپنی

shift_jisx0213

shiftjisx0213, sjisx0213, s_jisx0213

ژاپنی

utf_32

U32, utf32

تمام زبان‌ها

utf_32_be

UTF-32BE

تمام زبان‌ها

utf_32_le

UTF-32LE

تمام زبان‌ها

utf_16

U16, utf16

تمام زبان‌ها

utf_16_be

UTF-16BE

تمام زبان‌ها

utf_16_le

UTF-16LE

تمام زبان‌ها

utf_7

U7, unicode-1-1-utf-7

تمام زبان‌ها

utf_8

U8, UTF, utf8, cp65001

تمام زبان‌ها

utf_8_sig

تمام زبان‌ها

تغییر یافته در نسخه‌ی 3.4: کدگذارهای utf-16* و utf-32* دیگر اجازه نمی‌دهند نقاط کد جانشین (U+D800--U+DFFF) کدگذاری شوند. کدگشاهای utf-32* دیگر دنباله‌های بایتی متناظر با نقاط کد جانشین (surrogate code points) را کدگشایی نمی‌کنند.

تغییر یافته در نسخه‌ی 3.8: cp65001 اکنون نام مستعاری برای utf_8 است.

تغییر یافته در نسخه‌ی 3.14: در ویندوز، کدک‌های cpXXX اکنون برای همه‌ی صفحات کد در دسترس هستند.

کدگذاری‌های خاص پایتون

تعدادی از کدک‌های از پیش تعریف‌شده مختص پایتون هستند، بنابراین نام‌های کدک آن‌ها در خارج از پایتون معنایی ندارند. این موارد در جدول‌های زیر بر اساس انواع ورودی و خروجی مورد انتظار فهرست شده‌اند (توجه داشته باشید که اگرچه کدگذاری‌های متن رایج‌ترین مورد استفاده برای کدک‌ها هستند، زیرساخت زیربنایی کدک از تبدیل‌های دلخواه داده پشتیبانی می‌کند، نه فقط از کدگذاری‌های متن). در کدک‌های نامتقارن، معنای ذکرشده جهت کدگذاری را توصیف می‌کند.

کدگذاری‌های متن

کدک‌های زیر، مشابه کدگذاری‌های متنی یونیکد، کدگذاری از str به bytes و کدگشایی از bytes-like object به str را فراهم می‌کنند.

کدک

نام‌های مستعار

معنی

idna

پیاده‌سازی RFC 3490، همچنین encodings.idna را ببینید. فقط errors='strict' پشتیبانی می‌شود.

هشدار

This codec builds on punycode, whose algorithms scale poorly, so limit the length of untrusted input.

mbcs

ansi, dbcs

فقط ویندوز: عملوند را بر اساس صفحه‌کد ANSI (CP_ACP) کدگذاری می‌کند.

oem

فقط ویندوز: عملوند بر اساس صفحه‌کد OEM کدگذاری می‌شود (CP_OEMCP).

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

palmos

کدگذاری PalmOS 3.5.

punycode

پیاده‌سازی RFC 3492. کدک‌های حالت‌دار پشتیبانی نمی‌شوند.

هشدار

الگوریتم‌های کدگشایی و کدگذاری مقیاس‌پذیری ضعیفی دارند، بنابراین طول ورودی غیرقابل‌اعتماد را محدود کنید.

raw_unicode_escape

کدگذاری Latin-1 با \uXXXX و \UXXXXXXXX برای سایر نقاط کد. بک‌اسلش‌های موجود به هیچ وجه خنثی نمی‌شوند. این کدگذاری در پروتکل pickle پایتون استفاده می‌شود.

undefined

این کدک باید تنها برای اهداف آزمایشی استفاده شود.

برای همه تبدیل‌ها، حتی رشته‌های خالی، استثنا پرتاب می‌کند. هندلر خطا نادیده گرفته می‌شود.

unicode_escape

کدگذاری مناسب برای محتوای یک لفظی یونیکد در کد منبع پایتون با کدگذاری ASCII، به جز اینکه علامت‌های نقل‌قول خنثی نمی‌شوند. کدگشایی از کد منبع Latin-1. توجه داشته باشید که کد منبع پایتون در واقع به‌طور پیش‌فرض از UTF-8 استفاده می‌کند.

تغییر یافته در نسخه‌ی 3.8: کدک "unicode_internal" حذف شده است.

تبدیل‌های دودویی

کدک‌های زیر تبدیل‌های دودویی را ارائه می‌دهند: نگاشت‌هایی از شیء شبه‌بایت به bytes. bytes.decode() از آن‌ها پشتیبانی نمی‌کند (که تنها خروجی str را تولید می‌کند).

کدک

نام‌های مستعار

معنی

کدگذار / کدگشا

base64_codec [1]

base64, base_64

عملوند را به base64 MIME چندخطی تبدیل می‌کند (نتیجه همیشه شامل یک '\n' در انتها است).

تغییر یافته در نسخه‌ی 3.4: هر bytes-like object را به‌عنوان ورودی برای کدگذاری و کدگشایی می‌پذیرد

base64.encodebytes() / base64.decodebytes()

bz2_codec

bz2

عملوند را با استفاده از bz2 فشرده کنید.

bz2.compress() / bz2.decompress()

hex_codec

hex

عملوند را به نمایش مبنای شانزده تبدیل کنید، با ۲ رقم به‌ازای هر بایت.

binascii.b2a_hex() / binascii.a2b_hex()

quopri_codec

quopri, quotedprintable, quoted_printable

عملوند را به MIME quoted printable تبدیل کنید.

quopri.encode() با quotetabs=True / quopri.decode()

uu_codec

uu

عملوند را با استفاده از uuencode تبدیل کنید.

zlib_codec

zip, zlib

عملوند را با gzip فشرده کنید.

zlib.compress() / zlib.decompress()

اضافه شده در نسخه‌ی 3.2: بازیابی تبدیل‌های دودویی.

تغییر یافته در نسخه‌ی 3.4: بازگرداندن نام‌های مستعار برای تبدیل‌های دودویی.

توابع مستقل کدک

توابع زیر عملکرد کدگذاری و کدگشایی مشابه کدک‌ها را فراهم می‌کنند، اما به‌عنوان کدک‌های نام‌دار از طریق codecs.encode() یا codecs.decode() در دسترس نیستند. این توابع به‌صورت داخلی (برای مثال، توسط pickle) استفاده می‌شوند و رفتاری مشابه کدک string_escape دارند که در Python 3 حذف شده است.

codecs.escape_encode(input, errors=None)

کدگذاری input با استفاده از دنباله‌های خنثی‌سازی. مشابه روشی که repr() بر روی بایت‌ها مقادیر بایتی خنثی‌شده تولید می‌کند.

input باید یک شیء bytes باشد.

یک تاپل (output, length) برمی‌گرداند که در آن output یک شیء bytes و length تعداد بایت‌های مصرف‌شده است.

codecs.escape_decode(input, errors=None)

input را از دنباله‌های خنثی‌سازی به بایت‌های اصلی کدگشایی می‌کند.

input باید یک bytes-like object باشد.

یک تاپل (output, length) برمی‌گرداند که در آن output یک شیء bytes و length تعداد بایت‌های مصرف‌شده است.

تبدیل‌های متن

کدک زیر یک تبدیل متنی فراهم می‌کند: نگاشتی از str به str. str.encode() از آن پشتیبانی نمی‌کند (که فقط خروجی bytes تولید می‌کند).

کدک

نام‌های مستعار

معنی

rot_13

rot13

رمزنگاری سزاری عملوند را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.2: بازگردانی تبدیل متنی rot_13.

تغییر یافته در نسخه‌ی 3.4: بازگردانی نام مستعار rot13.

encodings --- بسته‌ی encodings

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

encodings.normalize_encoding(encoding)

نام کدگذاری encoding را عادی‌سازی کنید.

نرمال‌سازی به این صورت انجام می‌شود: همه‌ی نویسه‌های غیرحرفی‌عددی، به‌جز نقطه‌ای که در نام بسته‌های پایتون به کار می‌رود، فشرده می‌شوند و با یک زیرخط جایگزین می‌شوند؛ زیرسطرهای آغازین و پایانی حذف می‌شوند. برای مثال، '  -;#' به '_' تبدیل می‌شود.

توجه داشته باشید که encoding باید فقط ASCII باشد.

توجه

توابع زیر نباید به‌صورت مستقیم استفاده شوند، مگر برای اهداف آزمون؛ باید به‌جای آن‌ها از codecs.lookup() استفاده شود.

encodings.search_function(encoding)

ماژول کدک متناظر با نام کدگذاری داده‌شده encoding را جستجو کنید.

این تابع ابتدا encoding را با استفاده از normalize_encoding() به‌هنجار می‌کند، سپس به دنبال یک نام مستعار متناظر می‌گردد. این تابع تلاش می‌کند یک ماژول کدک را از بسته‌ی encodings با استفاده از نام مستعار یا نام به‌هنجارشده ایمپورت کند. اگر ماژول پیدا شود و تابع getregentry() معتبری را تعریف کند که یک شیء codecs.CodecInfo را برمی‌گرداند، کدک در نهانگاه ذخیره و برگردانده می‌شود.

اگر ماژول کدک تابع getaliases() را تعریف کند، هر نام مستعار برگردانده‌شده برای استفاده در آینده ثبت می‌شود.

encodings.win32_code_page_search_function(encoding)

یک کدگذاری صفحه‌کد ویندوز encoding به شکل cpXXXX را جستجو کنید.

اگر صفحه کد معتبر و پشتیبانی‌شده باشد، یک شیء codecs.CodecInfo برای آن برمی‌گرداند.

دسترس‌پذیری: Windows.

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

این ماژول استثنای زیر را پیاده‌سازی می‌کند:

exception encodings.CodecRegistryError

هنگامی که یک کدک نامعتبر یا ناسازگار باشد، پرتاب می‌شود.

encodings.idna --- نام‌های دامنه بین‌المللی‌شده در کاربردها

این ماژول RFC 3490 (نام‌های دامنه بین‌المللی‌سازی‌شده در کاربردها) و RFC 3492 (Nameprep: یک پروفایل Stringprep برای نام‌های دامنه بین‌المللی‌سازی‌شده (IDN)) را پیاده‌سازی می‌کند. این ماژول بر پایه‌ی کدگذاری punycode و stringprep ساخته شده است.

هشدار

This module builds on punycode, whose algorithms scale poorly, so limit the length of untrusted input.

اگر به استاندارد IDNA 2008 از RFC 5891 و RFC 5895 نیاز دارید، از ماژول شخص ثالث idna استفاده کنید.

این RFCها با هم یک پروتکل را برای پشتیبانی از نویسه‌های غیر ASCII در نام‌های دامنه تعریف می‌کنند. یک نام دامنه حاوی نویسه‌های غیر ASCII (مانند www.Alliancefrançaise.nu) به یک کدگذاری سازگار با ASCII (ACE، مانند www.xn--alliancefranaise-npb.nu) تبدیل می‌شود. سپس از شکل ACE نام دامنه در تمام جاهایی که پروتکل نویسه‌های دلخواه را مجاز نمی‌داند، مانند پرسمان‌های DNS، فیلدهای Host HTTP و غیره استفاده می‌شود. این تبدیل در برنامه انجام می‌شود؛ در صورت امکان، باید برای کاربر نامرئی باشد: برنامه باید برچسب‌های دامنه‌ی یونیکد را به‌صورت شفاف در شبکه به IDNA تبدیل کند و پیش از نمایش آن‌ها به کاربر، برچسب‌های ACE را به یونیکد بازگرداند.

پایتون از این تبدیل به چند روش پشتیبانی می‌کند: کدک idna تبدیل بین یونیکد و ACE را انجام می‌دهد، یک رشته ورودی را بر اساس نویسه‌های جداکننده تعریف‌شده در بخش 3.1 از RFC 3490 به برچسب‌ها تفکیک می‌کند و هر برچسب را در صورت نیاز به ACE تبدیل می‌کند، و برعکس، یک رشته بایتی ورودی را بر اساس جداکننده . به برچسب‌ها تفکیک می‌کند و هر برچسب ACE یافت‌شده را به یونیکد تبدیل می‌کند. علاوه بر این، ماژول socket نام‌های میزبان یونیکد را به‌صورت شفاف به ACE تبدیل می‌کند، تا برنامه‌ها هنگامی که نام‌های میزبان را به ماژول socket می‌دهند، نیازی نباشد خودشان آن‌ها را تبدیل کنند. افزون بر آن، ماژول‌هایی که نام‌های میزبان را به‌عنوان پارامترهای تابع دارند، مانند http.client و ftplib، نام‌های میزبان یونیکد را می‌پذیرند (در این صورت http.client همچنین به‌صورت شفاف یک نام میزبان IDNA را در فیلد Host ارسال می‌کند، اگر اصلاً آن فیلد را ارسال کند).

هنگام دریافت نام‌های میزبان از شبکه (مانند جستجوی معکوس نام)، هیچ تبدیل خودکاری به یونیکد انجام نمی‌شود: برنامه‌هایی که می‌خواهند چنین نام‌های میزبانی را به کاربر ارائه دهند، باید آن‌ها را به یونیکد کدگشایی کنند.

ماژول encodings.idna همچنین رویه‌ی nameprep را پیاده‌سازی می‌کند، که نرمال‌سازی‌های مشخصی را روی نام‌های میزبان انجام می‌دهد تا عدم حساسیت به بزرگی و کوچکی حروف در نام‌های دامنه بین‌المللی حاصل شود و نویسه‌های مشابه یکسان‌سازی شوند. در صورت تمایل می‌توان توابع nameprep را مستقیماً استفاده کرد.

encodings.idna.nameprep(label)

نسخه‌ی nameprepشده‌ی label را برمی‌گرداند. پیاده‌سازی در حال حاضر رشته‌های پرس‌وجو را فرض می‌کند، بنابراین AllowUnassigned برابر true است.

encodings.idna.ToASCII(label)

یک برچسب را به ASCII تبدیل می‌کند، همان‌طور که در RFC 3490 مشخص شده است. فرض می‌شود UseSTD3ASCIIRules false باشد.

encodings.idna.ToUnicode(label)

یک برچسب را به یونیکد تبدیل کنید، همان‌طور که در RFC 3490 مشخص شده است.

encodings.mbcs --- صفحه‌کد ANSI ویندوز

این ماژول صفحه کد ANSI (CP_ACP) را پیاده‌سازی می‌کند.

دسترس‌پذیری: Windows.

تغییر یافته در نسخه‌ی 3.2: پیش از 3.2، آرگومان errors نادیده گرفته می‌شد؛ برای کدگذاری همیشه از 'replace' و برای کدگشایی از 'ignore' استفاده می‌شد.

تغییر یافته در نسخه‌ی 3.3: از هر هندلر خطایی پشتیبانی می‌کند.

encodings.utf_8_sig --- کدک UTF-8 با امضای BOM

این ماژول گونه‌ای از کدک UTF-8 را پیاده‌سازی می‌کند. هنگام کدگذاری، یک BOM کدگذاری‌شده با UTF-8 به ابتدای بایت‌های کدگذاری‌شده با UTF-8 اضافه می‌شود. برای کدگذار حالت‌مند، این کار تنها یک بار انجام می‌شود (در نخستین نوشتن روی جریان بایت). هنگام کدگشایی، یک BOM اختیاری کدگذاری‌شده با UTF-8 در ابتدای داده نادیده گرفته می‌شود.