رجیستری کدک و توابع پشتیبانی

int PyCodec_Register(PyObject *search_function)

قسمتی از ABI پایدار.

یک تابع جستجوی کدک جدید را ثبت می‌کند.

به‌عنوان یک اثر جانبی، این تلاش می‌کند در صورتی که هنوز انجام نشده باشد، بسته‌ی encodings را بارگذاری کند تا مطمئن شود که همیشه در ابتدای فهرست توابع جستجو قرار دارد.

int PyCodec_Unregister(PyObject *search_function)

قسمتی از ABI پایدار از نسخه‌ی 3.10.

ثبت یک تابع جستجوی کدک را لغو می‌کند و نهانگاه رجیستری را پاک می‌کند. اگر تابع جستجو ثبت نشده باشد، هیچ کاری انجام نمی‌دهد. در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا ایجاد می‌کند و -1 را برمی‌گرداند.

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

int PyCodec_KnownEncoding(const char *encoding)

قسمتی از ABI پایدار.

بسته به اینکه برای encoding داده‌شده کدک ثبت‌شده‌ای وجود دارد یا خیر، 1 یا 0 برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyObject *PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

API عمومی کدگذاری مبتنی بر کدک.

object با استفاده از روش مدیریت خطای تعریف‌شده توسط errors، از تابع کدگذاری که برای encoding داده‌شده یافت شده است، عبور داده می‌شود. errors می‌تواند NULL باشد تا از روش پیش‌فرض تعریف‌شده برای کدک استفاده شود. در صورت یافت نشدن کدگذار، استثنای LookupError ایجاد می‌شود.

PyObject *PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

API عمومیِ کدگشایی مبتنی بر کدک.

object با استفاده از روش مدیریت خطای تعریف‌شده توسط errors، از تابع کدگشای یافت‌شده برای encoding داده‌شده عبور داده می‌شود. errors می‌تواند NULL باشد تا از روش پیش‌فرض تعریف‌شده برای کدک استفاده شود. اگر هیچ کدگشایی یافت نشود، استثنای LookupError ایجاد می‌شود.

API جستجوی کدک

در توابع زیر، رشته‌ی encoding پس از تبدیل به نویسه‌های تماماً کوچک جستجو می‌شود، که همین امر باعث می‌شود کدگذاری‌هایی که از طریق این سازوکار جستجو می‌شوند، عملاً بدون حساسیت به بزرگی و کوچکی نویسه‌ها باشند. اگر هیچ کدکی یافت نشود، یک KeyError تنظیم می‌شود و NULL برگردانده می‌شود.

PyObject *PyCodec_Encoder(const char *encoding)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

دریافت تابع کدگذار برای encoding داده‌شده.

PyObject *PyCodec_Decoder(const char *encoding)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

گرفتن تابع کدگشا برای کدگذاری داده‌شده.

PyObject *PyCodec_IncrementalEncoder(const char *encoding, const char *errors)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء IncrementalEncoder برای کدگذاری داده‌شده دریافت می‌کند.

PyObject *PyCodec_IncrementalDecoder(const char *encoding, const char *errors)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

به دست آوردن یک شیء IncrementalDecoder برای encoding داده‌شده.

PyObject *PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

گرفتن تابع کارخانه‌ای StreamReader برای کدگذاری داده‌شده.

PyObject *PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

دریافت یک تابع کارخانه‌ای StreamWriter برای کدگذاری داده‌شده.

API رجیستری برای هندلر‌های خطای کدگذاری یونیکد

int PyCodec_RegisterError(const char *name, PyObject *error)

قسمتی از ABI پایدار.

تابع کال‌بک مدیریت خطای error را با نام داده‌شده name ثبت می‌کند. این تابع کال‌بک توسط یک کدک زمانی فراخوانی می‌شود که به نویسه‌های غیرقابل کدگذاری/بایت‌های غیرقابل کدگشایی برخورد کند و name به‌عنوان پارامتر خطا در فراخوانی تابع کدگذاری/کدگشایی مشخص شده باشد.

کال‌بک یک آرگومان واحد دریافت می‌کند، نمونه‌ای از UnicodeEncodeError، UnicodeDecodeError یا UnicodeTranslateError که اطلاعاتی درباره‌ی دنباله‌ی مشکل‌ساز نویسه‌ها یا بایت‌ها و آفست آن‌ها در رشته‌ی اصلی نگه می‌دارد (برای توابعی که این اطلاعات را استخراج می‌کنند، به اشیاء استثنای یونیکد مراجعه کنید). کال‌بک باید یا استثنای داده‌شده را ایجاد کند، یا یک تاپل دوآیتمی بازگرداند که شامل جایگزین دنباله‌ی مشکل‌ساز و یک عدد صحیح است که مشخص می‌کند کدگذاری/کدگشایی باید از کدام آفست در رشته‌ی اصلی از سر گرفته شود.

در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند.

PyObject *PyCodec_LookupError(const char *name)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

تابع کال‌بک مدیریت خطای ثبت‌شده تحت نام name را جستجو می‌کند. به عنوان یک حالت خاص، می‌توان NULL را ارسال کرد که در این صورت کال‌بک مدیریت خطا برای "strict" بازگردانده می‌شود.

PyObject *PyCodec_StrictErrors(PyObject *exc)

مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار.

exc را به‌عنوان استثنا ایجاد می‌کند.

PyObject *PyCodec_IgnoreErrors(PyObject *exc)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

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

PyObject *PyCodec_ReplaceErrors(PyObject *exc)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

خطای کدگذاری یونیکد را با ? یا U+FFFD جایگزین کنید.

PyObject *PyCodec_XMLCharRefReplaceErrors(PyObject *exc)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

خطای کدگذاری یونیکد را با ارجاع‌های نویسه XML جایگزین می‌کند.

PyObject *PyCodec_BackslashReplaceErrors(PyObject *exc)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

خطای کدگذاری یونیکد را با گریزهای بک‌اسلش (\x، \u و \U) جایگزین می‌کند.

PyObject *PyCodec_NameReplaceErrors(PyObject *exc)

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.7.

خطای کدگذاری یونیکد را با گریزهای \N{...} جایگزین کنید.

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

متغیرهای کاربردی کدک

const char *Py_hexdigits

یک ثابت رشته‌ای که شامل ارقام مبنای شانزده با حروف کوچک است: "0123456789abcdef".

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