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

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

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

کدک هارمزگذاری (OBJ ، رمزگذاری = "UTF-8" ، خطاها = "سخت")

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

ممکن است خطاها برای تنظیم طرح استفاده از خطای مورد نظر انجام شود. کنترل کننده خطای پیش فرض "دقیق" است به این معنی که خطاهای رمزگذاری باعث افزایش ارزش گذاری (یا یک زیر کلاس خاص کدک مانند مانند unicodeencodeerror) می شوند. برای اطلاعات بیشتر در مورد رسیدگی به خطای کدک به کلاسهای پایه کدک مراجعه کنید.

کدک هارمزگشایی (OBJ ، رمزگذاری = "UTF-8" ، خطاها = "سخت")

با استفاده از کدک ثبت شده برای رمزگذاری ، OBJ را رمزگشایی می کند.

ممکن است خطاها برای تنظیم طرح استفاده از خطای مورد نظر انجام شود. کنترل کننده خطای پیش فرض "دقیق" است به این معنی که خطاهای رمزگشایی باعث افزایش ارزش گذاری (یا یک زیر کلاس خاص کدک ، مانند uniCodedEcodeError) می شوند. برای اطلاعات بیشتر در مورد رسیدگی به خطای کدک به کلاسهای پایه کدک مراجعه کنید.

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

کدک هاجستجو (رمزگذاری)

اطلاعات کدک را در رجیستری کدک پایتون جستجو می کند و یک شیء Codecinfo را مطابق شکل زیر باز می گرداند.

کدگذاری ها ابتدا در حافظه نهان رجیستری مورد بررسی قرار می گیرند. در صورت یافتن ، لیست توابع جستجوی ثبت شده اسکن می شود. اگر هیچ شیء Codecinfo پیدا نشود ، یک نگاهگر مطرح می شود. در غیر این صورت ، شیء Codecinfo در حافظه نهان ذخیره می شود و به تماس گیرنده باز می گردد.

کدک های کلاس. CodeCinfo (رمزگذاری ، رمزگشایی ، streamReader = هیچ ، streamwriter = هیچ ، endrementalencoder = none ، incrementaldecoder = none ، name = none) ¶

جزئیات کدک هنگام جستجوی رجیستری کدک. آرگومان های سازنده در ویژگی هایی با همین نام ذخیره می شوند:

نام رمزگذاری.

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

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

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

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

کدک هاGetEncoder (رمزگذاری)

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

در صورت عدم یافتن رمزگذاری ، یک نگاه کننده را بالا می برد.

کدک هاgetDecoder (رمزگذاری)

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

در صورت عدم یافتن رمزگذاری ، یک نگاه کننده را بالا می برد.

کدک هاGetIncrementalEncoder (رمزگذاری)

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

در صورت عدم یافتن رمزگذاری یا کدک از یک رمزگذار افزایشی پشتیبانی نمی کند.

کدک هاGetIncrementalDecoder (رمزگذاری)

کدک را برای رمزگذاری داده شده جستجو کنید و کلاس یا عملکرد رمزگشایی افزایشی آن را برگردانید.

در صورت عدم یافتن رمزگذاری یا کدک از رمزگشایی افزایشی پشتیبانی نمی کند.

کدک هاgetReader (رمزگذاری)

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

در صورت عدم یافتن رمزگذاری ، یک نگاه کننده را بالا می برد.

کدک هاGetWriter (رمزگذاری)

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

در صورت عدم یافتن رمزگذاری ، یک نگاه کننده را بالا می برد.

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

کدک هاثبت نام (search_function)

یک عملکرد جستجوی کدک را ثبت کنید. انتظار می رود توابع جستجو یک آرگومان را در نظر بگیرند ، که نام رمزگذاری در تمام حروف کوچک با Hyphens و فضاهایی است که به زیربناها تبدیل شده و یک شیء Codecinfo را بازگرداند. در صورتی که یک تابع جستجو نتواند رمزگذاری معین را پیدا کند ، باید هیچ کدام را بازگرداند.

در نسخه 3. 9 تغییر یافته است: Hyphens و Spaces به تأکید شده تبدیل می شوند.

کدک هاثبت نام نشده (search_function)

یک عملکرد جستجوی کدک را ثبت نام کرده و حافظه پنهان رجیستری را پاک کنید. اگر عملکرد جستجو ثبت نشده است ، هیچ کاری نکنید.

جدید در نسخه 3. 10.

در حالی که ماژول داخلی و ماژول IO مرتبط با آن ، رویکرد توصیه شده برای کار با فایل های متنی رمزگذاری شده است ، این ماژول توابع و کلاسهای ابزار اضافی را ارائه می دهد که امکان استفاده از طیف وسیع تری از کدک ها را هنگام کار با پرونده های باینری فراهم می کند:

کدک هاباز (نام پرونده ، حالت = 'r' ، رمزگذاری = هیچ ، خطاها = "سخت" ، بافر = - 1)

یک فایل رمزگذاری شده را با استفاده از حالت داده شده باز کنید و نمونه ای از StreamReaderWriter را برگردانید و رمزگذاری/رمزگشایی شفاف را ارائه دهید. حالت فایل پیش فرض "R" است ، به معنای باز کردن پرونده در حالت Read.

اگر رمزگذاری هیچکدام نباشد ، فایلهای رمزگذاری شده زیرین همیشه در حالت باینری باز می شوند. هیچ تبدیل خودکار از " n" در خواندن و نوشتن انجام نمی شود. آرگومان حالت ممکن است هر حالت باینری قابل قبول برای عملکرد داخلی باز () باشد."B" به طور خودکار اضافه می شود.

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

ممکن است برای تعریف خطای خطا خطاها انجام شود. این پیش فرض به "سختگیرانه" است که در صورت بروز خطای رمزگذاری ، باعث افزایش یک ارزش می شود.

بافر همان معنای عملکرد داخلی () باز () را دارد. این به طور پیش فرض ب ه-1 است ، به این معنی که از اندازه بافر پیش فرض استفاده می شود.

در نسخه 3. 11 تغییر کرده است: حالت "U" حذف شده است.

کدک هاEncodedFile (پرونده ، data_encoding ، file_encoding = هیچ ، خطاها = "سخت")

یک نمونه StreamRecoder را برگردانید ، یک نسخه بسته بندی شده از پرونده که کدگذاری شفاف را ارائه می دهد. وقتی نسخه بسته بندی شده بسته شد ، پرونده اصلی بسته می شود.

داده های نوشته شده به پرونده بسته بندی شده با توجه به داده های داده شده داده شده رمزگشایی می شوند و سپس با استفاده از File_Encoding برای پرونده اصلی به صورت بایت نوشته می شوند. بایت های خوانده شده از پرونده اصلی مطابق با File_Encoding رمزگشایی می شوند و نتیجه با استفاده از data_encoding رمزگذاری می شود.

اگر File_Encoding داده نشود ، به Data_Encoding پیش فرض می شود.

ممکن است برای تعریف خطای خطا خطاها انجام شود. این پیش فرض به "سخت" است ، که باعث می شود در صورت بروز خطای رمزگذاری ، ارزش گذاری را افزایش دهد.

کدک هاiterencode (تکرار ، رمزگذاری ، خطاها = "سخت" ، ** kwargs)

از یک رمزگذار افزایشی برای کدگذاری مکرر ورودی ارائه شده توسط تکرار کننده استفاده می کند. این تابع یک ژنراتور است. آرگومان خطاها (و همچنین هر آرگومان کلیدواژه دیگری) به رمزگذار افزایشی ارسال می شود.

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

کدک هاiterdecode ( تکرار کننده، رمزگذاری، خطاها = 'سخت'، ** kwargs) ¶

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

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

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

کدک هاکدک های BOM ¶. BOM_BE ¶ کدک. BOM_LE ¶ کدک. کدک های BOM_UTF8 ¶. کدک های BOM_UTF16 ¶. کدک های BOM_UTF16_BE ¶. کدک های BOM_UTF16_LE ¶. کدک های BOM_UTF32 ¶. کدک های BOM_UTF32_BE ¶. 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 هستند.

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

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

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

کنترل کننده خطا¶

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

>>> "آلمانی ß، ♬".رمزگذاری کنید(رمزگذاری="اسکی", خطاها="backslashreplace") b'آلمانی \xdf, \u266c' >>> "آلمانی ß، ♬".رمزگذاری کنید(رمزگذاری="اسکی", خطاها='xmlcharrefreplace') b'آلمانی ß, ♬' 

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

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

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

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

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

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

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

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

با N جایگزین کنید<.>دنباله های فرار، آنچه در پرانتزها ظاهر می شود، ویژگی Name از پایگاه داده کاراکترهای یونیکد است. در namereplace_errors() پیاده سازی شد.

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

utf-8، utf-16، utf-32، utf-16-be، utf-16-le، utf-32-be، utf-32-le

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

جدید در نسخه 3. 1: کنترل کننده خطای 'srogateescape' و 'srogatepass'.

تغییر در نسخه 3. 4: کنترل کننده خطای 'srogatepass' اکنون با کدک های utf-16* و utf-32* کار می کند.

جدید در نسخه 3. 5: کنترل کننده خطای 'namereplace'.

تغییر در نسخه 3. 5: کنترل کننده خطای 'backslashreplace' اکنون با رمزگشایی و ترجمه کار می کند.

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

کدک هاregister_error ( نام , error_handler ) ¶

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

برای رمزگذاری ، ERROR_HANDLER با یک نمونه unicodeencodeerror فراخوانی می شود ، که حاوی اطلاعاتی در مورد محل خطا است. کنترل کننده خطا باید این یا یک استثناء متفاوت را مطرح کند ، یا یک توپی را با جایگزینی برای قسمت غیرقابل کنترل ورودی و موقعیتی که رمزگذاری باید ادامه یابد ، برگرداند. جایگزینی ممکن است یا STR یا بایت باشد. اگر جایگزینی بایت باشد ، رمزگذار به سادگی آنها را در بافر خروجی کپی می کند. اگر جایگزینی یک رشته باشد ، رمزگذار جایگزینی را رمزگذاری می کند. رمزگذاری در ورودی اصلی در موقعیت مشخص ادامه دارد. مقادیر موقعیت منفی نسبت به انتهای رشته ورودی رفتار می شود. اگر موقعیت حاصل از آن خارج باشد ، indexerror مطرح می شود.

رمزگشایی و ترجمه به طور مشابه آثار ، به جز unicodedEcodeError یا unicodetranslateerror به کنترل کننده منتقل می شود و جایگزینی از دستیار خطا به طور مستقیم در خروجی قرار می گیرد.

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

کدک هاlookup_error (نام)

کنترل کننده خطا را که قبلاً با نام نام ثبت شده بود ، برگردانید.

در صورت عدم یافتن کنترل کننده ، یک نگاه کننده را بالا می برد.

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

کدک هاstrict_errors (استثنا)

رسیدگی به خطای "سخت" را اجرا می کند.

هر خطای رمزگذاری یا رمزگشایی یک unicodeerror را ایجاد می کند.

کدک هاIgnore_errors (استثنا)

رسیدگی به خطای "نادیده" را پیاده سازی می کند.

داده های ناقص نادیده گرفته می شود. رمزگذاری یا رمزگشایی بدون اطلاع بیشتر ادامه دارد.

کدک هاreplace_errors (استثنا)

رسیدگی به خطای "جایگزین" را اجرا می کند.

جایگزین ها؟(کاراکتر ASCII) برای رمزگذاری خطاها یا � (U+FFFD ، شخصیت جایگزین رسمی) برای رمزگشایی خطاهای.

کدک هاbackslashreplace_errors (استثنا)

رسیدگی به خطای "backslashreplace" را اجرا می کند.

داده های ناهنجار با یک دنباله فرار از پشتی جایگزین می شوند. در رمزگذاری ، از فرم hexadecimal نقطه کد یونیکد با فرمت ها xhh uxxxx uxxxxxxxx استفاده کنید. در رمزگشایی ، از فرم شش ضلعی مقدار بایت با فرمت xhh استفاده کنید.

تغییر در نسخه 3. 5: با رمزگشایی و ترجمه کار می کند.

کدک هاxmlcharrefreplace_errors (استثنا)

استفاده از خطای "XMLCHARREFREPLATE" را اجرا می کند (برای رمزگذاری فقط در رمزگذاری متن).

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

کدک هاnamereplace_errors (استثنا)

استفاده از خطای "namereplace" را اجرا می کند (برای رمزگذاری فقط در رمزگذاری متن).

شخصیت غیرقابل انکار توسط n جایگزین می شود<.>دنباله فرار. مجموعه شخصیت هایی که در بریس ظاهر می شوند ، ویژگی نام از پایگاه داده شخصیت Unicode است. به عنوان مثال ، حرف کوچک آلمانی "ß" به توالی بایت تبدیل می شود n.

جدید در نسخه 3. 5.

رمزگذاری و رمزگشایی بدون تابعیت

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

کدکرمزگذاری (ورودی ، خطاها = "سخت")

ورودی شی را رمزگذاری کرده و یک Tuple (شیء خروجی ، طول مصرف شده) را برمی گرداند. به عنوان مثال ، رمزگذاری متن با استفاده از یک رمزگذاری مجموعه کاراکتر خاص (به عنوان مثال ، CP1252 یا ISO-8859-1) یک شیء رشته را به یک شیء بایت تبدیل می کند.

آرگومان خطاها برای استفاده از خطای خطای را تعریف می کند. این به پیش فرض "سختگیرانه" است.

این روش ممکن است حالت را در نمونه کدک ذخیره نکند. از streamwriter برای کدک هایی استفاده کنید که باید حالت را حفظ کنند تا رمزگذاری کارآمد باشد.

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

کدکرمزگشایی (ورودی ، خطاها = "سخت")

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

برای رمزگذاری متن و کدک های بایت به بایت ، ورودی باید یک شیء بایت یا یکی از آنها باشد که رابط بافر فقط خواندنی را فراهم می کند-به عنوان مثال ، اشیاء بافر و فایل های نقشه برداری شده حافظه.

آرگومان خطاها برای استفاده از خطای خطای را تعریف می کند. این به پیش فرض "سختگیرانه" است.

این روش ممکن است حالت را در نمونه کدک ذخیره نکند. از streamReader برای کدک هایی استفاده کنید که باید حالت را حفظ کنند تا رمزگشایی کارآمد باشد.

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

رمزگذاری و رمزگشایی افزایشی

کلاسهای افزایشی و IncrementalDecoder رابط اساسی برای رمزگذاری و رمزگشایی افزایشی ارائه می دهند. رمزگذاری/رمزگشایی ورودی با یک تماس به عملکرد رمزگذار/رمزگذار بدون تابعیت انجام نمی شود ، بلکه با تماس های متعدد به روش رمزگذاری ()/رمزگشایی () رمزگذار/رمزگشایی افزایشی. رمزگذار/رمزگذار افزایشی روند رمزگذاری/رمزگشایی را در طی تماس های روش پیگیری می کند.

خروجی پیوسته تماس ها به روش رمزگذاری ()/رمزگشایی () همان است که گویی تمام ورودی های منفرد به یک وصل می شوند و این ورودی با رمزگذار/رمزگذار بدون تابش رمزگذاری شده/رمزگشایی شده است.

اشیاء افزایشی

از کلاس افزایش دهنده برای رمزگذاری ورودی در چندین مرحله استفاده می شود. این روشهای زیر را تعریف می کند که هر رمزگذار افزایشی باید تعریف کند تا با رجیستری کدک پایتون سازگار باشد.

کدک های کلاس. admentalencoder (خطاها = "سخت")

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

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

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

استدلال خطاها به یک ویژگی با همین نام اختصاص می یابد. اختصاص به این ویژگی باعث می شود که بین استراتژی های مختلف کنترل خطای مختلف در طول عمر شیء افزایش دهنده تغییر یابد.

رمزگذاری (شی ، نهایی = نادرست)

رمزگذاری شیء (با در نظر گرفتن وضعیت فعلی رمزگذار) و شیء رمزگذاری شده حاصل را برمی گرداند. اگر این آخرین تماس برای رمزگذاری است () نهایی باید درست باشد (پیش فرض نادرست است).

رمزگذار را به حالت اولیه تنظیم کنید. خروجی دور ریخته می شود: تماس . encode (شی ، نهایی = درست) ، عبور از یک بایت خالی یا رشته متن در صورت لزوم ، برای تنظیم مجدد رمزگذار و دریافت خروجی.

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

وضعیت رمزگذار را به حالت بیان کنید. حالت باید یک دولت رمزگذار باشد که توسط GetState () بازگردانده شده است.

IncrementalDecoder اشیاء

کلاس IncrementalDecoder برای رمزگشایی یک ورودی در چند مرحله استفاده می شود. روش های زیر را تعریف می کند که هر رمزگشای افزایشی باید تعریف کند تا با رجیستری کدک پایتون سازگار باشد.

کدک های کلاسIncrementalDecoder ( خطاها = 'سخت') ¶

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

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

IncrementalDecoder ممکن است طرح های مختلف مدیریت خطا را با ارائه آرگومان کلمه کلیدی خطاها پیاده سازی کند. برای مقادیر احتمالی به Error Handlers مراجعه کنید.

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

رمزگشایی (شیء، نهایی = نادرست) ¶

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

رمزگشا را به حالت اولیه بازگردانید.

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

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

رمزگذاری و رمزگشایی جریان¶

کلاسهای StreamWriter و StreamReader رابط های کاری عمومی را ارائه می دهند که می توانند برای اجرای زیرمجازهای رمزگذاری جدید به راحتی استفاده شوند. برای نمونه ای از نحوه انجام این کار به رمزگذاری ها مراجعه کنید.

streamwriter اشیاء

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

کدک های کلاس. StreamWriter (جریان ، خطاها = "سخت")

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

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

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

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

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

مطالب شیء رمزگذاری شده به جریان را می نویسد.

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

بافرهای کدک مورد استفاده برای نگه داشتن وضعیت داخلی را مجدداً تنظیم می کند.

فراخوانی این روش باید اطمینان حاصل کند که داده های موجود در خروجی در حالت پاک قرار داده شده است که اجازه می دهد تا داده های تازه جدید را بدون نیاز به بازگرداندن کل جریان برای بازیابی حالت ، اضافه کند.

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

streamReader اشیاء

کلاس StreamReader یک زیر کلاس از کدک است و روشهای زیر را تعریف می کند که هر خواننده جریان باید تعریف کند تا با رجیستری کدک پایتون سازگار باشد.

کدک های کلاس. StreamReader (جریان ، خطاها = "سخت")

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

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

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

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

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

مجموعه مقادیر مجاز برای آرگومان خطاها را می توان با Register_Error () گسترش داد.

بخوانید (اندازه = - 1 ، chars = - 1 ، firstline = false)

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

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

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

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

این روش باید از یک استراتژی خواندن حریص استفاده کند به این معنی که باید به همان اندازه داده ها را که در تعریف رمزگذاری و اندازه داده شده مجاز است ، بخواند ، به عنوان مثال. اگر انتهای رمزگذاری اختیاری یا نشانگرهای حالت در جریان موجود باشد ، این موارد نیز باید خوانده شوند.

readline (اندازه = هیچ ، نگهدارنده = درست)

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

در صورت ارائه ، اندازه به عنوان آرگومان اندازه به روش خوانده شده جریان () منتقل می شود.

اگر نگهدارنده باشد ، خطوط خط کاذب از خطوط برگشتی محروم می شوند.

readlines (sizehint = هیچ یک ، نگهدارنده = درست)

تمام خطوط موجود در جریان ورودی را بخوانید و آنها را به عنوان لیستی از خطوط برگردانید.

انتهای خط با استفاده از روش رمزگشایی کد () کدک اجرا می شود و در صورت صحت نگه داشتن در لیست های لیست گنجانده شده است.

در صورت ارائه ، به عنوان آرگومان اندازه به روش خوانده شده جریان () منتقل می شود.

بافرهای کدک مورد استفاده برای نگه داشتن وضعیت داخلی را مجدداً تنظیم می کند.

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

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

streamReaderWriter اشیاء

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

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

کدک های کلاس. StreamReaderWriter (جریان ، خواننده ، نویسنده ، خطاها = "سخت")

یک نمونه StreamReaderWriter ایجاد می کند. جریان باید یک شیء مانند پرونده باشد. خواننده و نویسنده باید توابع کارخانه یا کلاس هایی باشند که رابط streamReader و StreamWriter را ارائه می دهند. رسیدگی به خطا به همان روشی انجام می شود که برای خوانندگان و نویسندگان جریان تعریف شده است.

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

streamrecoder اشیاء

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

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

کدک های کلاس. StreamRecoder (جریان ، رمزگذاری ، رمزگشایی ، خواننده ، نویسنده ، خطاها = "سخت")

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

شما می توانید از این اشیاء برای انجام تراریخته های شفاف ، به عنوان مثال ، از لاتی ن-1 تا UTF-8 و عقب استفاده کنید.

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

آرگومان رمزگذاری و رمزگشایی باید به رابط کدک پایبند باشد. خواننده و نویسنده باید توابع کارخانه یا کلاس هایی باشند که به ترتیب اشیاء رابط StreamReader و StreamWriter را ارائه می دهند.

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

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

رمزگذاری و unicode¶

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

ساده ترین رمزگذاری متن (به نام "لاتی ن-1" یا "ISO-8859-1") نقاط کد 0-255 را به بایت 0x0-0xff نقشه می کند ، به این معنی که یک شیء رشته ای که حاوی نقاط کد بالاتر از u+00ff است می تواند "t با این کدک رمزگذاری می شود. انجام این کار یک unicodeencodeerror را که به نظر زیر می رسد ، ایجاد می کند (اگرچه جزئیات پیام خطا ممکن است متفاوت باشد): unicodeencodeerror: "لاتی ن-1" کدک نمی تواند شخصیت " u1234" را در موقعیت 3 رمزگذاری کند: ترتیب در محدوده (256).

گروه دیگری از رمزگذاری ها (رمزگذاری به اصطلاح Charmap) وجود دارد که زیر مجموعه های متفاوتی از تمام نقاط کد Unicode و نحوه نقشه برداری این نقاط کد به بایت های 0x0 - 0xff را انتخاب می کند. برای دیدن چگونگی انجام این کار به سادگی باز است. رمزگذاری/cp1252. py (که رمزگذاری است که در درجه اول در ویندوز استفاده می شود). یک رشته ثابت با 256 کاراکتر وجود دارد که به شما نشان می دهد کدام شخصیت برای کدام مقدار بایت نقشه برداری می شود.

همه این رمزگذاری ها فقط می توانند 256 از نقاط کد 1114112 را در یونیکد رمزگذاری کنند. یک روش ساده و ساده که می تواند هر نقطه کد یونیکد را ذخیره کند ، ذخیره هر نقطه کد به عنوان چهار بایت متوالی است. دو امکان وجود دارد: بایت ها را به صورت بزرگ Endian یا به ترتیب کمی Endian ذخیره کنید. این دو رمزگذاری به ترتیب UTF-32-BE و UTF-32-LE نامیده می شوند. نقطه ضعف آنها این است که اگر به عنوان مثالشما از UTF-32-Be در یک دستگاه Endian Little استفاده می کنید ، همیشه مجبور خواهید بود که بایت را در رمزگذاری و رمزگشایی عوض کنید. UTF-32 از این مشکل جلوگیری می کند: بایت ها همیشه در حالت طبیعی قرار می گیرند. هنگامی که این بایت ها توسط یک CPU با یک پایان متفاوت خوانده می شوند ، پس باید بایت ها تعویض شوند. برای اینکه بتوانیم نتیجه یک توالی بایت UTF-16 یا UTF-32 را تشخیص دهیم ، به اصطلاح BOM ("علامت سفارش بایت") وجود دارد. این شخصیت Unicode U+FEFF است. این شخصیت را می توان برای هر دنباله بایت UTF-16 یا UTF-32 پیش بینی کرد. نسخه مبادله شده بایت این شخصیت (0xFFFE) شخصیتی غیرقانونی است که ممکن است در یک متن یونیکد ظاهر نشود. بنابراین ، هنگامی که اولین شخصیت در یک دنباله بایت UTF-16 یا UTF-32 به نظر می رسد یک U+FFFE است که بایت ها باید در رمزگشایی تعویض شوند. متأسفانه شخصیت U+FEFF به عنوان یک فضای بدون شکن عرض صفر هدف دوم داشت: شخصیتی که عرض ندارد و اجازه نمی دهد کلمه تقسیم شود. به عنوان مثال می تواندبرای ارائه نکات به یک الگوریتم لیگور استفاده می شود. با استفاده از Unicode 4. 0 با استفاده از U+FEFF به عنوان یک فضای بدون شکست با عرض صفر (با U+2060 (Word Joiner) با فرض این نقش) کاهش یافته است. با این وجود ، نرم افزار یونیکد هنوز هم باید بتواند U+FEFF را در هر دو نقش اداره کند: به عنوان یک بمب دستگاهی برای تعیین طرح ذخیره سازی بایت های رمزگذاری شده است و پس از رمزگشایی توالی بایت در یک رشته ، از بین می رود. به عنوان یک فضای صفر بدون شکستن ، این یک شخصیت عادی است که مانند سایر موارد رمزگشایی می شود.

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