نوع یونیکد¶

این‌ها انواع پایه‌ای شیء یونیکد هستند که در پیاده‌سازی یونیکد در پایتون استفاده می‌شوند:

PyTypeObject PyUnicode_Type¶

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

این نمونه از PyTypeObject نمایانگر نوع یونیکد پایتون است. این نوع در کد پایتون به‌صورت str در دسترس قرار می‌گیرد.

PyTypeObject PyUnicodeIter_Type¶

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

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

type Py_UCS4¶

type Py_UCS2¶

type Py_UCS1¶

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

این نوع‌ها تعریف‌های نوع (typedef) برای نوع‌های عدد صحیح بدون علامت‌اند که به اندازه‌ی کافی پهن هستند تا بتوانند به ترتیب نویسه‌های ۳۲ بیتی، ۱۶ بیتی و ۸ بیتی را در خود جای دهند. هنگام کار با نویسه‌های منفرد یونیکد، از Py_UCS4 استفاده کنید.

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

type PyASCIIObject¶

type PyCompactUnicodeObject¶

type PyUnicodeObject¶

این زیرنوع‌های PyObject نمایانگر یک شیء یونیکد پایتون هستند. در تقریباً همه موارد، نباید مستقیماً از آن‌ها استفاده شود، زیرا تمام توابع API که با اشیاء یونیکد سروکار دارند، اشاره‌گرهای PyObject می‌گیرند و برمی‌گردانند.

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

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

PyUnicode_IS_COMPACT(o)¶

درست است اگر o از ساختار PyCompactUnicodeObject استفاده کند.

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

PyUnicode_IS_COMPACT_ASCII(o)¶

در صورتی که o از ساختار PyASCIIObject استفاده کند، درست است.

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

APIهای زیر ماکروهای C و توابع درون‌خطی ایستا برای بررسی‌های سریع و دسترسی به داده‌های داخلی فقط‌خواندنی اشیاء یونیکد هستند:

int PyUnicode_Check(PyObject *obj)¶

اگر شیء obj یک شیء یونیکد یا نمونه‌ای از یک زیرنوع یونیکد باشد، مقدار true برمی‌گرداند. این تابع همیشه با موفقیت انجام می‌شود.

int PyUnicode_CheckExact(PyObject *obj)¶

اگر شیء obj یک شیء یونیکد باشد، اما نمونه‌ای از یک زیرنوع نباشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶

طول رشته یونیکد را بر حسب نقطه‌کد برمی‌گرداند. unicode باید یک شیء یونیکد در نمایش «کانونیکال» باشد (بررسی نمی‌شود).

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

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)¶

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)¶

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)¶

اشاره‌گری به نمایش کانونیکال قالب‌ریزی‌شده به نوع‌های عدد صحیح UCS1، UCS2 یا UCS4 را برای دسترسی مستقیم به نویسه برمی‌گرداند. هیچ بررسی‌ای انجام نمی‌شود که آیا نمایش کانونیکال اندازه‌ی درست نویسه را دارد یا خیر؛ برای انتخاب تابع درست از PyUnicode_KIND() استفاده کنید.

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

PyUnicode_1BYTE_KIND¶

PyUnicode_2BYTE_KIND¶

PyUnicode_4BYTE_KIND¶

مقادیر بازگشتی ماکروی PyUnicode_KIND().

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

تغییر یافته در نسخه‌ی 3.12: PyUnicode_WCHAR_KIND حذف شده است.

int PyUnicode_KIND(PyObject *unicode)¶

یکی از ثابت‌های kind مربوط به PyUnicode (که در بالا آمده‌اند) را برمی‌گرداند که نشان می‌دهند این شیء یونیکد برای ذخیره داده‌های خود از چند بایت به ازای هر نویسه استفاده می‌کند. unicode باید یک شیء یونیکد در نمایش «کانونیکال» باشد (بررسی نمی‌شود).

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

void *PyUnicode_DATA(PyObject *unicode)¶

یک اشاره‌گر void به بافر خام یونیکد برمی‌گرداند. unicode باید یک شیء یونیکد در نمایش «کانونیکال» باشد (بررسی نمی‌شود).

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

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)¶

مقدار نقطه‌کد را در اندیس داده‌شده‌ی مبتنی بر صفر درون یک رشته می‌نویسد.

مقدار kind و اشاره‌گر data باید به ترتیب از یک رشته با استفاده از PyUnicode_KIND() و PyUnicode_DATA() به‌دست آمده باشند. شما باید هنگام فراخوانی PyUnicode_WRITE()، ارجاعی به آن رشته را نگه دارید. تمام الزامات PyUnicode_WriteChar() نیز اعمال می‌شوند.

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

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

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶

یک نقطه‌کد را از داده‌های بازنمایی کانونی data بخوانید (همان‌طور که با PyUnicode_DATA() به دست می‌آید). هیچ بررسی انجام نمی‌شود.

خواندن نویسه‌ی تهی پایانی در اندیس PyUnicode_GetLength() را بپذیرید.

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

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶

یک نویسه از شیء یونیکد unicode می‌خواند که باید در نمایش «کانونیکال» باشد. اگر چندین خواندن متوالی انجام می‌دهید، این کارایی کمتری نسبت به PyUnicode_READ() دارد.

خواندن نویسه‌ی تهی پایانی در اندیس PyUnicode_GetLength() را بپذیرید.

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

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶

بیشینه نقطه‌کدی را برمی‌گرداند که برای ایجاد رشته‌ای دیگر بر اساس unicode مناسب است؛ unicode باید در نمایش «کانونیکال» باشد. این همیشه یک تقریب است، اما از پیمایش کردن رشته کارآمدتر است.

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

int PyUnicode_IsIdentifier(PyObject *unicode)¶

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

اگر رشته مطابق تعریف زبان، بخش نام‌ها (شناسه‌ها و کلیدواژه‌ها)، یک شناسه‌ی معتبر باشد، 1 را برمی‌گرداند. در غیر این صورت 0 را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.9: اگر رشته آماده نباشد، این تابع دیگر Py_FatalError() را فراخوانی نمی‌کند.

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)¶

اگر رشته فقط شامل نویسه‌های اسکی باشد، مقدار درست را برمی‌گرداند. معادل str.isascii() است.

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

Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)¶

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

اگر هش str که توسط PyObject_Hash() برگردانده می‌شود، نهانگاه‌شده باشد و فوراً در دسترس باشد، آن را برگردانید. در غیر این صورت، بدون تنظیم کردن یک استثنا، -1 را برگردانید.

اگر str یک رشته نباشد (یعنی اگر PyUnicode_Check(obj) نادرست باشد)، رفتار نامشخص است.

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

توجه کنید هیچ تضمینی وجود ندارد که هش یک شیء چه زمانی نهانگاه شود، و وجود (یا عدم‌وجود) یک هش نهانگاه‌شده به این معنا نیست که رشته ویژگی‌های دیگری دارد.

ویژگی‌های نویسه‌ی یونیکد¶

یونیکد ویژگی‌های نویسه‌ی متعدد و گوناگونی را فراهم می‌کند. پرکاربردترین آن‌ها از طریق این ماکروها در دسترس‌اند که بسته به پیکربندی پایتون به توابع C نگاشت می‌شوند.

int Py_UNICODE_ISSPACE(Py_UCS4 ch)¶

بسته به این‌که ch یک نویسه فاصله‌ساز باشد یا نه، 1 یا 0 برمی‌گرداند.

int Py_UNICODE_ISLOWER(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه‌ی کوچک باشد یا نه، 1 یا 0 را برمی‌گرداند.

int Py_UNICODE_ISUPPER(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه‌ی بزرگ باشد یا نه، 1 یا 0 را برمی‌گرداند.

int Py_UNICODE_ISTITLE(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه‌ی عنوان‌نویسی‌شده باشد یا نه، 1 یا 0 را برمی‌گرداند.

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه شکست سطر باشد یا نه، 1 یا 0 را برمی‌گرداند.

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه ده‌دهی باشد یا نه، 1 یا 0 را برمی‌گرداند.

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه رقم باشد یا نه، 1 یا 0 را برمی‌گرداند.

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)¶

بسته به این‌که ch یک نویسه عددی باشد یا نه، 1 یا 0 برمی‌گرداند.

int Py_UNICODE_ISALPHA(Py_UCS4 ch)¶

بسته به این‌که ch یک نویسه الفبایی باشد یا نه، 1 یا 0 برمی‌گرداند.

int Py_UNICODE_ISALNUM(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه الفبایی-عددی باشد یا نه، 1 یا 0 را برمی‌گرداند.

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)¶

بسته به اینکه ch یک نویسه‌ی چاپ‌پذیر در معنای str.isprintable() باشد یا نه، مقدار 1 یا 0 را برمی‌گرداند.

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

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)¶

نویسه‌ی ch را به حروف کوچک تبدیل‌شده برمی‌گرداند.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)¶

نویسه ch را که به حروف بزرگ تبدیل شده است برمی‌گرداند.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)¶

نویسه ch تبدیل‌شده به نگارش عنوان‌نویسی را بازمی‌گرداند.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)¶

نویسه ch را به صورت یک عدد صحیح مثبت ده‌دهی تبدیل‌شده برمی‌گرداند. اگر این کار ممکن نباشد، -1 برمی‌گرداند. این تابع استثنا ایجاد نمی‌کند.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶

نویسه ch را به یک عدد صحیح تک‌رقمی تبدیل‌شده برمی‌گرداند. اگر این کار ممکن نباشد، -1 برمی‌گرداند. این تابع استثنا ایجاد نمی‌کند.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶

نویسه ch را به یک عدد ممیز شناور با دقت مضاعف تبدیل‌شده برمی‌گرداند. اگر این کار ممکن نباشد، -1.0 را برمی‌گرداند. این تابع استثنا ایجاد نمی‌کند.

می‌توان از این APIها برای کار با جانشین‌ها استفاده کرد:

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)¶

بررسی می‌کند که آیا ch جانشین است یا خیر (0xD800 <= ch <= 0xDFFF).

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)¶

بررسی کنید که ch جانشین بالایی باشد (0xD800 <= ch <= 0xDBFF).

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)¶

بررسی کنید که آیا ch یک جانشین پایین است (0xDC00 <= ch <= 0xDFFF).

Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)¶

بازگرداندن جانشین بالای UTF-16 (0xD800 تا 0xDBFF) برای یک نقطه‌کد یونیکد در بازه‌ی [0x10000; 0x10FFFF].

Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)¶

جانشین پایین UTF-16 (0xDC00 تا 0xDFFF) را برای یک نقطه‌کد یونیکد در محدوده‌ی [0x10000; 0x10FFFF] بازمی‌گرداند.

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)¶

دو نقطه‌کد جانشین را به هم می‌پیوندد و یک مقدار Py_UCS4 برمی‌گرداند. high و low به ترتیب جانشین پیشرو و جانشین پسرو در یک جفت جانشین هستند. high باید در محدوده‌ی [0xD800; 0xDBFF] و low باید در محدوده‌ی [0xDC00; 0xDFFF] باشد.

ایجاد و دسترسی به رشته‌های یونیکد¶

برای ایجاد اشیاء یونیکد و دسترسی به ویژگی‌های پایه‌ی دنباله‌ی آن‌ها، از این API‌ها استفاده کنید:

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶

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

یک شیء یونیکد جدید ایجاد کنید. maxchar باید حداکثر نقطه‌کد واقعی‌ای باشد که در رشته قرار می‌گیرد. به‌عنوان یک تقریب، می‌توان آن را رو به بالا به نزدیک‌ترین مقدار در دنباله‌ی ۱۲۷، ۲۵۵، ۶۵۵۳۵، ۱۱۱۴۱۱۱ گرد کرد.

در صورت خطا، یک استثنا تنظیم کنید و NULL را برگردانید.

پس از ایجاد، می‌توان رشته را با PyUnicode_WriteChar()، PyUnicode_CopyCharacters()، PyUnicode_Fill()، PyUnicode_WRITE() یا توابع مشابه پر کرد. از آنجا که رشته‌ها باید تغییرناپذیر باشند، مراقب باشید که نتیجه را هنگام تغییر «استفاده» نکنید. به‌طور خاص، پیش از آنکه با محتوای نهایی خود پر شود، یک رشته:

• نباید هش شود،

• نباید به UTF-8 تبدیل شود، یا به بازنمایی غیر«کانونیکال» دیگری تبدیل شود،

• نباید شمارش ارجاع آن تغییر داده شود،

• نباید با کدی که ممکن است یکی از موارد فوق را انجام دهد به اشتراک گذاشته شود.

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

برای جلوگیری از افشای ناخواسته‌ی شیء رشته‌ی نیمه‌نوشته، استفاده از API PyUnicodeWriter یا یکی از توابع PyUnicode_From* زیر را ترجیح دهید.

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

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)¶

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

یک شیء یونیکد جدید با kind داده‌شده ایجاد می‌کند (مقادیر ممکن عبارت‌اند از PyUnicode_1BYTE_KIND و غیره، همان‌طور که توسط PyUnicode_KIND() برگردانده می‌شوند). buffer باید به آرایه‌ای از size واحدِ ۱، ۲ یا ۴ بایتی به ازای هر نویسه اشاره کند، همان‌طور که توسط kind مشخص شده است.

در صورت نیاز، بافر ورودی کپی شده و به نمایش کانونیکال تبدیل می‌شود. برای مثال، اگر بافر یک رشته‌ی UCS4 باشد (PyUnicode_4BYTE_KIND) و تنها شامل نقطه‌کدهایی در محدوده‌ی UCS1 باشد، به UCS1 تبدیل می‌شود (PyUnicode_1BYTE_KIND).

تمام نویسه‌ها باید در محدوده‌ی [U+0000; U+10ffff] باشند. اگر kind برابر با PyUnicode_4BYTE_KIND باشد و رشته شامل نویسه‌های نامعتبر باشد، رفتار نامعلوم است.

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

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)¶

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

یک شیء یونیکد از بافر نویسه str ایجاد می‌کند. بایت‌ها به‌عنوان کدگذاری‌شده با UTF-8 تفسیر می‌شوند. بافر در شیء جدید کپی می‌شود. مقدار بازگشتی ممکن است یک شیء مشترک باشد، یعنی تغییر داده‌ها مجاز نیست.

این تابع در موارد زیر استثنای SystemError را ایجاد می‌کند:

• size < 0,

• str برابر NULL است و size > 0

تغییر یافته در نسخه‌ی 3.12: str == NULL همراه با size > 0 دیگر مجاز نیست.

PyObject *PyUnicode_FromString(const char *str)¶

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

یک شیء یونیکد از بافر نویسه‌ی کدگذاری‌شده با UTF-8 و پایان‌یافته با تهی str ایجاد می‌کند.

PyObject *PyUnicode_FromFormat(const char *format, ...)¶

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

یک رشته قالب به سبک printf()در C و تعداد متغیری از آرگومان‌ها می‌گیرد، اندازه‌ی رشته‌ی یونیکد پایتونِ حاصل را محاسبه می‌کند و رشته‌ای را که مقادیر در آن قالب‌بندی شده‌اند برمی‌گرداند. آرگومان‌های متغیر باید نوع‌های C باشند و دقیقاً با نویسه‌های قالب در رشته قالب کدگذاری‌شده با اسکی مطابقت داشته باشند.

مشخص‌کننده تبدیل شامل دو نویسه یا بیشتر است و دارای اجزای زیر است که باید به این ترتیب ظاهر شوند:

1. نویسه‌ی '%' که آغاز مشخص‌کننده را علامت‌گذاری می‌کند.

2. پرچم‌های تبدیل (اختیاری) که بر نتیجه‌ی برخی از نوع‌های تبدیل تأثیر می‌گذارند.

3. حداقل عرض میدان (اختیاری). اگر به‌صورت '*' (ستاره) مشخص شود، عرض واقعی در آرگومان بعدی داده می‌شود که باید از نوع int باشد، و شیء‌ای که باید تبدیل شود، پس از حداقل عرض میدان و دقت اختیاری قرار می‌گیرد.

4. دقت (اختیاری)، به‌صورت '.' (نقطه) و به دنبال آن مقدار دقت داده می‌شود. اگر به‌صورت '*' (ستاره) تعیین شود، دقت واقعی در آرگومان بعدی داده می‌شود که باید از نوع int باشد، و مقداری که باید تبدیل شود پس از دقت می‌آید.

5. اصلاح‌کننده‌ی طول (اختیاری).

6. نوع تبدیل.

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

پرچم	معنا
0	تبدیل برای مقادیر عددی با صفر پر خواهد شد.
-	مقدار تبدیل‌شده چپ‌تراز می‌شود (اگر هر دو داده شوند، پرچم 0 نادیده گرفته می‌شود).

اصلاح‌کننده‌های طول برای تبدیل‌های عدد صحیح زیر (d، i، o، u، x یا X) نوع آرگومان را تعیین می‌کنند (int به‌طور پیش‌فرض):

اصلاح‌گر	نوع‌ها
l	long یا unsigned long
ll	long long یا unsigned long long
j``	intmax_t یا uintmax_t
z	size_t یا ssize_t
t	ptrdiff_t

اصلاح‌کننده‌ی طول l برای تبدیل‌های بعدی s یا V مشخص می‌کند که نوع آرگومان const wchar_t* است.

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

مشخص‌کننده تبدیل	نوع	کامنت
%	n/a	نویسه‌ی لفظی %.
d, i	تعیین‌شده توسط اصلاح‌گر طول (length modifier)	نمایش دهدهی یک عدد صحیح علامت‌دار در C.
u	تعیین‌شده توسط اصلاح‌گر طول (length modifier)	نمایش مبنای ده یک عدد صحیح بدون علامت C.
o	تعیین‌شده توسط اصلاح‌گر طول (length modifier)	نمایش مبنای هشت یک عدد صحیح بدون علامت C.
x	تعیین‌شده توسط اصلاح‌گر طول (length modifier)	نمایش مبنای شانزده‌ی یک عدد صحیح بدون علامت C (با حروف کوچک).
X	تعیین‌شده توسط اصلاح‌گر طول (length modifier)	نمایش مبنای شانزده‌ی یک عدد صحیح بدون علامت C (با حروف بزرگ).
c	int	یک نویسه.
s	const char* یا const wchar_t*	آرایه‌ی نویسه‌ای C که با نویسه‌ی تهی پایان می‌یابد.
p	const void*	نمایش مبنای شانزده‌ی یک اشاره‌گر C. عمدتاً معادل printf("%p") است، با این تفاوت که تضمین می‌شود صرف‌نظر از آنچه printf پلتفرم تولید می‌کند، با مقدار لفظی 0x آغاز شود.
A	PyObject*	نتیجه فراخوانی ascii().
U	PyObject*	یک شیء یونیکد.
V	PyObject*، const char* یا const wchar_t*	یک شیء یونیکد (که ممکن است NULL باشد) و یک آرایه‌ی نویسه‌ای C پایان‌یافته با نویسه تهی به‌عنوان پارامتر دوم (که اگر پارامتر اول NULL باشد، استفاده خواهد شد).
S	PyObject*	نتیجه فراخوانی PyObject_Str().
R	PyObject*	نتیجه‌ی فراخوانی PyObject_Repr().
T``	PyObject*	برای به‌دست‌آوردن نام کامل نوع یک شیء، PyType_GetFullyQualifiedName() را فراخوانی کنید.
#T	PyObject*	شبیه به قالب T، اما از دونقطه (:) به‌عنوان جداکننده بین نام ماژول و نام کامل استفاده می‌کند.
N	PyTypeObject*	نام کامل یک نوع را دریافت کنید؛ PyType_GetFullyQualifiedName() را فراخوانی کنید.
#N	PyTypeObject*	مشابه قالب N، اما از دونقطه (:) به عنوان جداکننده بین نام ماژول و نام کامل استفاده می‌کند.

نکته

واحد قالب‌بند عرض، تعداد نویسه‌ها است نه بایت‌ها. واحد قالب‌بند دقت برای "%s" و "%V" (اگر آرگومان PyObject* برابر با NULL باشد)، تعداد بایت‌ها یا آیتم‌های wchar_t (در صورت استفاده از اصلاح‌کننده طول l) است، و برای "%A"، "%U"، "%S"، "%R" و "%V" (اگر آرگومان PyObject* برابر با NULL نباشد)، تعداد نویسه‌ها است.

نکته

برخلاف printf() در C، پرچم 0 حتی وقتی دقتی برای تبدیل‌های عدد صحیح (d، i، u، o، x یا X) تعیین شده باشد، اثر دارد.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از "%lld" و "%llu" افزوده شد.

تغییر یافته در نسخه‌ی 3.3: پشتیبانی از "%li"، "%lli" و "%zi" افزوده شد.

تغییر یافته در نسخه‌ی 3.4: پشتیبانی از قالب‌بند عرض و دقت برای "%s"، "%A"، "%U"، "%V"، "%S"، "%R" افزوده شد.

تغییر یافته در نسخه‌ی 3.12: پشتیبانی از مشخص‌کننده‌های تبدیل o و X. پشتیبانی از اصلاح‌کننده‌های طول j و t. اصلاح‌کننده‌های طول اکنون بر همه‌ی تبدیل‌های عدد صحیح اعمال می‌شوند. اصلاح‌کننده‌ی طول l اکنون بر مشخص‌کننده‌های تبدیل s و V اعمال می‌شود. پشتیبانی از عرض و دقت متغیر *. پشتیبانی از پرچم -.

اکنون نویسه‌ی قالب‌بندی ناشناخته یک SystemError ایجاد می‌کند. در نسخه‌های قبلی، این نویسه باعث می‌شد تمام بقیه‌ی رشته‌ی قالب عیناً در رشته‌ی نتیجه رونوشت شود و هر آرگومان اضافی دور ریخته شود.

تغییر یافته در نسخه‌ی 3.13: پشتیبانی از قالب‌های %T، %#T، %N و %#N افزوده شد.

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)¶

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

یکسان با PyUnicode_FromFormat() است، با این تفاوت که دقیقاً دو آرگومان می‌گیرد.

PyObject *PyUnicode_FromObject(PyObject *obj)¶

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

در صورت نیاز، یک نمونه از یک زیرنوع یونیکد را به یک شیء یونیکد واقعی جدید کپی می‌کند. اگر obj از قبل یک شیء یونیکد واقعی باشد (نه یک زیرنوع)، یک ارجاع قوی جدید به همان شیء برمی‌گرداند.

اشیایی غیر از یونیکد یا زیرنوع‌های آن باعث ایجاد TypeError خواهند شد.

PyObject *PyUnicode_FromOrdinal(int ordinal)¶

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

یک شیء یونیکد از ترتیبیِ نقطه‌کد یونیکدِ داده‌شده ایجاد می‌کند.

مقدار ترتیبی باید در range(0x110000) باشد. در صورتی که چنین نباشد، استثنای ValueError مطرح می‌شود.

PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)¶

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

یک شیء کدگذاری‌شده obj را به یک شیء یونیکد کدگشایی می‌کند.

bytes، bytearray و سایر اشیاء شبه‌بایت بر اساس encoding داده‌شده و با استفاده از مدیریت خطای تعریف‌شده توسط errors کدگشایی می‌شوند. هر دو می‌توانند NULL باشند تا رابط از مقادیر پیش‌فرض استفاده کند (برای جزئیات به کدک‌های توکار مراجعه کنید).

تمام اشیاء دیگر، از جمله اشیاء یونیکد، باعث می‌شوند استثنای TypeError تنظیم شود.

در صورت وقوع خطا، این API مقدار NULL را برمی‌گرداند. کاهش شمارش ارجاع (decref) اشیاء برگردانده‌شده بر عهده‌ی فراخواننده است.

void PyUnicode_Append(PyObject **p_left, PyObject *right)¶

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

رشته right را به انتهای p_left اضافه کنید. p_left باید به یک ارجاع قوی به یک شیء یونیکد اشاره کند؛ PyUnicode_Append() این ارجاع را آزاد می‌کند ("می‌دزدد").

در صورت خطا، *p_left را برابر NULL قرار دهید و یک استثنا تنظیم کنید.

در صورت موفقیت، *p_left را برابر با ارجاع قوی جدیدی به نتیجه قرار می‌دهد.

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)¶

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

این تابع مشابه PyUnicode_Append() است و تنها تفاوت آن این است که شمارش ارجاع right را یکی کاهش می‌دهد.

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)¶

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

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

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

const char *PyUnicode_GetDefaultEncoding(void)¶

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

نام کدگذاری پیش‌فرض رشته، "utf-8" را برمی‌گرداند. به sys.getdefaultencoding() مراجعه کنید.

رشته‌ی بازگردانده‌شده نیازی به آزاد شدن ندارد و تا خاموش شدن مفسر معتبر است.

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶

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

طول شیء یونیکد را بر حسب نقطه‌کد برمی‌گرداند.

در صورت خطا، یک استثنا تنظیم شده و -1 بازگردانده می‌شود.

طول، نویسه‌ی پایانی تهی را حساب نمی‌کند.

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

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)¶

نویسه‌ها را از یک شیء یونیکد به شیء یونیکد دیگر کپی می‌کند. این تابع در صورت نیاز تبدیل نویسه‌ها را انجام می‌دهد و در صورت امکان به memcpy() روی می‌آورد. در صورت خطا -1 برمی‌گرداند و یک استثنا تنظیم می‌کند، در غیر این صورت تعداد نویسه‌های کپی‌شده را برمی‌گرداند.

رشته نباید هنوز «استفاده شده» باشد. برای جزئیات به PyUnicode_New() مراجعه کنید.

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

int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);¶

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

اندازه یک شیء یونیکد *unicode را به length جدید بر حسب نقطه‌کد تغییر دهید.

سعی کنید رشته را درجا تغییر اندازه دهید (که معمولاً سریع‌تر از تخصیص دادن یک رشته جدید و کپی کردن نویسه‌ها است)، یا یک رشته جدید ایجاد کنید.

*unicode به‌گونه‌ای تغییر می‌کند که به شیء جدید (تغییر اندازه‌یافته) اشاره کند و در صورت موفقیت 0 بازگردانده می‌شود. در غیر این صورت، -1 بازگردانده می‌شود، یک استثنا تنظیم می‌شود و *unicode دست‌نخورده باقی می‌ماند.

این تابع محتوای رشته را بررسی نمی‌کند و نتیجه ممکن است رشته‌ای در نمایش کانونیکال نباشد.

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)¶

پر کردن یک رشته با یک نویسه: نوشتن fill_char در unicode[start:start+length].

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

رشته نباید هنوز «استفاده شده» باشد. برای جزئیات به PyUnicode_New() مراجعه کنید.

تعداد نویسه‌های نوشته‌شده را برمی‌گرداند، یا در صورت خطا -1 را برمی‌گرداند و استثنا raise می‌کند.

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

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)¶

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

نویسه‌ی character را در اندیس مبنای صفرِ index از رشته‌ی unicode می‌نویسد. در صورت موفقیت 0 و در صورت خطا با تنظیم یک استثنا -1 برمی‌گرداند.

این تابع بررسی می‌کند که unicode یک شیء یونیکد باشد، که اندیس خارج از محدوده نباشد، و اینکه شمارش ارجاع شیء برابر با یک باشد. برای نسخه‌ای که این بررسی‌ها را انجام نمی‌دهد و مسئولیت آن‌ها را بر عهده‌ی شما می‌گذارد، به PyUnicode_WRITE() مراجعه کنید.

رشته نباید هنوز «استفاده شده» باشد. برای جزئیات به PyUnicode_New() مراجعه کنید.

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

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶

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

یک نویسه از یک رشته می‌خواند. این تابع بررسی می‌کند که unicode یک شیء یونیکد باشد و اندیس خارج از کران‌ها نباشد، برخلاف PyUnicode_READ_CHAR() که هیچ بررسی خطایی انجام نمی‌دهد.

در صورت موفقیت نویسه و در صورت خطا -1 را همراه با استثنای تنظیم‌شده برمی‌گرداند.

خواندن نویسه‌ی پایانی تهی در اندیس PyUnicode_GetLength() پذیرفته نمی‌شود.

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

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶

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

زیررشته‌ای از unicode را برمی‌گرداند که از اندیس نویسه‌ی start (شامل) تا اندیس نویسه‌ی end (بدون) است. اندیس‌های منفی پشتیبانی نمی‌شوند. در صورت خطا، یک استثنا تنظیم کرده و NULL را برمی‌گرداند.

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

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶

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

رشته unicode را در یک بافر UCS4 کپی می‌کند و در صورت تنظیم بودن copy_null، یک نویسه تهی نیز در آن گنجانده می‌شود. در صورت خطا، NULL را برمی‌گرداند و یک استثنا تنظیم می‌کند (به‌طور خاص، SystemError در صورتی که buflen کوچک‌تر از طول unicode باشد). در صورت موفقیت، buffer را برمی‌گرداند.

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

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶

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

رشته unicode را به یک بافر UCS4 جدید که با استفاده از PyMem_Malloc() تخصیص داده‌شده است، کپی می‌کند. اگر این کار ناموفق باشد، NULL برگردانده می‌شود و MemoryError تنظیم می‌شود. بافر برگردانده‌شده همیشه یک نقطه‌کد تهی اضافی در انتهای خود دارد.

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

کدگذاری locale¶

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

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)¶

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

یک رشته را در اندروید و VxWorks از UTF-8، یا در پلتفرم‌های دیگر از کدگذاری locale جاری کدگشایی می‌کند. هندلرهای خطای پشتیبانی‌شده "strict" و "surrogateescape" هستند (PEP 383). کدگشا در صورتی که errors NULL باشد، از هندلر خطای "strict" استفاده می‌کند. str باید با یک نویسه تهی پایان یابد، اما نمی‌تواند شامل نویسه‌های تهی تعبیه‌شده باشد.

از PyUnicode_DecodeFSDefaultAndSize() برای کدگشایی یک رشته از filesystem encoding and error handler استفاده کنید.

این تابع حالت UTF-8 پایتون را نادیده می‌گیرد.

همچنین ببینید

تابع Py_DecodeLocale().

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

تغییر یافته در نسخه‌ی 3.7: این تابع اکنون برای هندلر خطای surrogateescape از کدگذاری locale جاری نیز استفاده می‌کند، به‌جز در اندروید. پیش‌تر، Py_DecodeLocale() برای surrogateescape استفاده می‌شد و کدگذاری locale جاری برای strict به کار می‌رفت.

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)¶

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

مشابه PyUnicode_DecodeLocaleAndSize()، اما طول رشته را با استفاده از strlen() محاسبه می‌کند.

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

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)¶

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

یک شیء یونیکد را در اندروید و VxWorks به UTF-8، یا در پلتفرم‌های دیگر به کدگذاری locale جاری کدگذاری می‌کند. هندلرهای خطای پشتیبانی‌شده عبارت‌اند از "strict" و "surrogateescape" (PEP 383). کدگذار در صورت NULL بودن errors از هندلر خطای "strict" استفاده می‌کند. یک شیء bytes برمی‌گرداند. unicode نمی‌تواند حاوی نویسه‌های تهی تعبیه‌شده باشد.

برای کدگذاری یک رشته به filesystem encoding and error handler از PyUnicode_EncodeFSDefault() استفاده کنید.

این تابع حالت UTF-8 پایتون را نادیده می‌گیرد.

همچنین ببینید

تابع Py_EncodeLocale().

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

تغییر یافته در نسخه‌ی 3.7: این تابع اکنون برای هندلر خطای surrogateescape نیز از کدگذاری locale جاری استفاده می‌کند، به‌جز در اندروید. پیش‌تر، برای surrogateescape از Py_EncodeLocale() استفاده می‌شد و برای strict از کدگذاری locale جاری به کار می‌رفت.

کدگذاری سامانه فایل‌بندی¶

توابعی که به filesystem encoding and error handler کدگذاری و از آن کدگشایی می‌کنند (PEP 383 و PEP 529).

برای کدگذاری نام پرونده‌ها به bytes در حین پارس آرگومان‌ها، باید از مبدل "O&" استفاده کرد و PyUnicode_FSConverter() را به‌عنوان تابع تبدیل‌کننده ارسال کرد:

int PyUnicode_FSConverter(PyObject *obj, void *result)¶

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

مبدل PyArg_Parse*: اشیاء str را -- که مستقیماً یا از طریق رابط os.PathLike به دست آمده‌اند -- با استفاده از PyUnicode_EncodeFSDefault() به bytes کدگذاری می‌کند؛ اشیاء bytes بدون تغییر خروجی داده می‌شوند. result باید آدرس یک متغیر C از نوع PyObject* (یا PyBytesObject*) باشد. در صورت موفقیت، متغیر را روی یک ارجاع قوی جدید به شیء بایت تنظیم می‌کند که باید هنگامی که دیگر استفاده نمی‌شود آزاد شود و یک مقدار ناصفر (Py_CLEANUP_SUPPORTED) برمی‌گرداند. بایت‌های تهی تعبیه‌شده در نتیجه مجاز نیستند. در صورت شکست، 0 را همراه با تنظیم یک استثنا برمی‌گرداند.

اگر obj برابر NULL باشد، تابع ارجاع قوی ذخیره‌شده در متغیری را که result به آن ارجاع می‌دهد آزاد می‌کند و 1 را برمی‌گرداند.

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

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

برای کدگشایی نام پرونده‌ها به str در حین تجزیه آرگومان‌ها، باید از مبدل "O&" استفاده کرد و PyUnicode_FSDecoder() را به‌عنوان تابع تبدیل‌کننده پاس داد:

int PyUnicode_FSDecoder(PyObject *obj, void *result)¶

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

مبدل PyArg_Parse*: اشیاء bytes را -- که به‌طور مستقیم یا غیرمستقیم از طریق رابط os.PathLike به دست آمده‌اند -- با استفاده از PyUnicode_DecodeFSDefaultAndSize() به str کدگشایی می‌کند؛ اشیاء str بدون تغییر به خروجی داده می‌شوند. result باید نشانی یک متغیر C از نوع PyObject* (یا PyUnicodeObject*) باشد. در صورت موفقیت، متغیر را به یک ارجاع قوی جدید به شیء یونیکد -- که باید هنگامی که دیگر استفاده نمی‌شود آزاد شود -- تنظیم می‌کند و یک مقدار ناصفر (Py_CLEANUP_SUPPORTED) را برمی‌گرداند. نتیجه نمی‌تواند شامل نویسه‌های تهی تعبیه‌شده باشد. در صورت شکست، 0 را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

اگر obj برابر NULL باشد، ارجاع قوی به شیء‌ای را که result به آن ارجاع می‌دهد آزاد کنید و 1 را بازگردانید.

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

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)¶

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

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

اگر نیاز دارید رشته‌ای را از کدگذاری locale جاری کدگشایی کنید، از PyUnicode_DecodeLocaleAndSize() استفاده کنید.

همچنین ببینید

تابع Py_DecodeLocale().

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

PyObject *PyUnicode_DecodeFSDefault(const char *str)¶

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

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

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

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

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

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

یک شیء یونیکد را به filesystem encoding and error handler کدگذاری می‌کند و bytes برمی‌گرداند. توجه داشته باشید که شیء bytes حاصل می‌تواند شامل بایت‌های تهی باشد.

اگر نیاز دارید رشته‌ای را به کدگذاری locale جاری کدگذاری کنید، از PyUnicode_EncodeLocale() استفاده کنید.

همچنین ببینید

تابع Py_EncodeLocale().

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

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

پشتیبانی از wchar_t¶

پشتیبانی از wchar_t برای پلتفرم‌هایی که از آن پشتیبانی می‌کنند:

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)¶

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

یک شیء یونیکد از بافر wchar_t به نام wstr با اندازه‌ی داده‌شده size می‌سازد. گذراندن -1 به عنوان size نشان می‌دهد که خودِ تابع باید طول را با استفاده از wcslen() محاسبه کند. در صورت شکست، NULL بازمی‌گرداند.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)¶

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

محتوای شیء یونیکد را در بافر wstr از نوع wchar_t کپی می‌کند. حداکثر size نویسه‌ی wchar_t کپی می‌شود (بدون احتساب نویسه‌ی پایانی تهی که ممکن است در انتها باشد). تعداد نویسه‌های wchar_t کپی‌شده را برمی‌گرداند و در صورت بروز خطا -1.

وقتی wstr برابر NULL باشد، به‌جای آن اندازه*‌ای که برای ذخیره‌ی تمام *unicode شامل یک تهی پایانی لازم است، بازگردانده می‌شود.

توجه داشته باشید که رشته‌ی حاصلِ wchar_t* ممکن است تهی‌پایان (null-terminated) باشد یا نباشد. اطمینان از تهی‌پایان بودن رشته‌ی wchar_t* در صورتی که برنامه به آن نیاز داشته باشد، بر عهده‌ی فراخوان‌کننده است. همچنین توجه داشته باشید که رشته‌ی wchar_t* ممکن است حاوی نویسه‌های تهی باشد، که این امر باعث می‌شود رشته هنگام استفاده در بیشتر توابع C بریده شود.

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)¶

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

شیء یونیکد را به یک رشته نویسه پهن تبدیل می‌کند. رشته خروجی همیشه با یک نویسه تهی پایان می‌یابد. اگر size برابر NULL نباشد، تعداد نویسه‌های پهن (بدون احتساب نویسه تهی پایانی) در *size نوشته می‌شود. توجه داشته باشید که رشته wchar_t حاصل ممکن است شامل نویسه‌های تهی باشد، که این امر باعث می‌شود رشته هنگام استفاده با بیشتر توابع C قطع شود. اگر size برابر NULL باشد و رشته wchar_t* شامل نویسه‌های تهی باشد، ValueError مطرح می‌شود.

در صورت موفقیت، بافر تخصیص‌یافته توسط PyMem_New را برمی‌گرداند (برای آزاد کردن آن از PyMem_Free() استفاده کنید). در صورت خطا، NULL برمی‌گرداند و *size تعریف‌نشده است. در صورت شکست تخصیص حافظه، استثنای MemoryError را ایجاد می‌کند.

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

تغییر یافته در نسخه‌ی 3.7: اگر size برابر NULL باشد و رشته‌ی wchar_t* شامل نویسه‌های تهی باشد، استثنای ValueError را مطرح می‌کند.

کدک‌های عمومی¶

ماکروی زیر ارائه شده است:

Py_UNICODE_REPLACEMENT_CHARACTER¶

نقطه‌کد یونیکد U+FFFD (نویسه جایگزینی).

اگر آرگومان errors روی "replace" تنظیم شده باشد، از این نویسه‌ی یونیکد در حین کدگشایی به‌عنوان نویسه‌ی جایگزین استفاده می‌شود.

این‌ها APIهای کدک عام هستند:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)¶

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

با کدگشایی size بایت از رشته کدگذاری‌شده str، یک شیء یونیکد ایجاد می‌کند. encoding و errors همان معنای پارامترهای هم‌نام در تابع توکار str() را دارند. کدک مورد استفاده با بهره‌گیری از رجیستری کدک پایتون جستجو می‌شود. اگر استثنایی توسط کدک ایجاد‌شده باشد، NULL برمی‌گرداند.

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)¶

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

یک شیء یونیکد را کدگذاری می‌کند و نتیجه را به‌صورت شیء بایتی پایتون برمی‌گرداند. encoding و errors همان معنای پارامترهای هم‌نام در متد encode() یونیکد را دارند. کدک مورد استفاده از طریق رجیستری کدک پایتون جستجو می‌شود. اگر کدک استثنایی ایجاد کرده باشد، NULL را برمی‌گرداند.

کدک‌های UTF-8¶

این‌ها APIهای کدک UTF-8 هستند:

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)¶

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

یک شیء یونیکد با کدگشایی size بایت از رشته‌ی کدگذاری‌شده با UTF-8 به نام str ایجاد می‌کند. اگر کدک استثنایی ایجاد کرده باشد، مقدار NULL را برمی‌گرداند.

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

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

اگر consumed برابر NULL باشد، مانند PyUnicode_DecodeUTF8() رفتار می‌کند. اگر consumed برابر NULL نباشد، دنباله‌های بایتی ناقص انتهایی UTF-8 به عنوان خطا در نظر گرفته نمی‌شوند. این بایت‌ها کدگشایی نمی‌شوند و تعداد بایت‌هایی که کدگشایی شده‌اند در consumed ذخیره می‌شود.

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)¶

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

یک شیء یونیکد را با استفاده از UTF-8 کدگذاری می‌کند و نتیجه را به‌صورت شیء بایت پایتون برمی‌گرداند. مدیریت خطا «strict» است. اگر کدک استثنایی مطرح کرده باشد، NULL را برمی‌گرداند.

در صورتی که رشته شامل نقطه‌کدهای جانشین باشد، این تابع شکست می‌خورد (U+D800 - U+DFFF).

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)¶

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

یک اشاره‌گر به کدگذاری UTF-8 شیء یونیکد را برمی‌گرداند و اندازه‌ی بازنمایش کدگذاری‌شده (بر حسب بایت) را در size ذخیره می‌کند. آرگومان size می‌تواند NULL باشد؛ در این حالت هیچ اندازه‌ای ذخیره نمی‌شود. بافر بازگردانده‌شده همیشه یک بایت تهی اضافی در انتها دارد (که در size حساب نمی‌شود)، صرف‌نظر از اینکه نقاط کد تهی دیگری وجود داشته باشد یا نه.

در صورت خطا، یک استثنا تنظیم کنید، size را برابر -1 قرار دهید (اگر NULL نباشد) و NULL را برگردانید.

در صورتی که رشته شامل نقطه‌کدهای جانشین باشد، این تابع شکست می‌خورد (U+D800 - U+DFFF).

این کار نمایش UTF-8 رشته را در شیء یونیکد نهانگاه‌سازی می‌کند و فراخوانی‌های بعدی اشاره‌گری به همان بافر را برمی‌گردانند. فراخواننده مسئول آزاد کردن بافر نیست. زمانی که شیء یونیکد زباله‌روبی شود، بافر آزاد می‌شود و اشاره‌گرهایی که به آن اشاره می‌کنند، نامعتبر می‌شوند.

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

تغییر یافته در نسخه‌ی 3.7: نوع بازگشتی اکنون const char * به‌جای char * است.

تغییر یافته در نسخه‌ی 3.10: این تابع بخشی از API محدود است.

const char *PyUnicode_AsUTF8(PyObject *unicode)¶

مانند PyUnicode_AsUTF8AndSize()، اما اندازه را ذخیره نمی‌کند.

هشدار

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

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

تغییر یافته در نسخه‌ی 3.7: نوع بازگشتی اکنون const char * به‌جای char * است.

کدک‌های UTF-32¶

این‌ها APIهای کُدک UTF-32 هستند:

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶

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

بایت‌های size را از یک رشته بافر کدگذاری‌شده با UTF-32 کدگشایی می‌کند و شیء یونیکد متناظر را برمی‌گرداند. errors (در صورت NULL نبودن) برخورد با خطا را تعیین می‌کند. مقدار پیش‌فرض آن "strict" است.

اگر byteorder غیر از NULL باشد، کدگشا کدگشایی را با استفاده از ترتیب بایت داده‌شده آغاز می‌کند:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

اگر *byteorder صفر باشد و چهار بایت نخست داده‌های ورودی، نشانگر ترتیب بایت (BOM) باشند، کدگشا به این ترتیب بایت تغییر می‌کند و BOM در رشته یونیکد حاصل کپی نمی‌شود. اگر *byteorder برابر -1 یا 1 باشد، هر نشانگر ترتیب بایتی به خروجی کپی می‌شود.

پس از اتمام، *byteorder به ترتیب بایت جاری در انتهای داده‌های ورودی تنظیم می‌شود.

اگر byteorder برابر NULL باشد، کدک در حالت ترتیب بومی آغاز می‌کند.

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

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶

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

اگر consumed برابر NULL باشد، مانند PyUnicode_DecodeUTF32() رفتار می‌کند. اگر consumed برابر NULL نباشد، PyUnicode_DecodeUTF32Stateful() دنباله‌های بایتی ناقص انتهایی UTF-32 (مانند تعدادی بایت که بر چهار بخش‌پذیر نیست) را به عنوان خطا در نظر نمی‌گیرد. این بایت‌ها کدگشایی نمی‌شوند و تعداد بایت‌هایی که کدگشایی شده‌اند در consumed ذخیره می‌شود.

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶

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

یک رشته بایتی پایتون را با استفاده از کدگذاری UTF-32 به ترتیب بایت بومی برمی‌گرداند. این رشته همیشه با نشانگر ترتیب بایت آغاز می‌شود. مدیریت خطا «strict» است. اگر استثنایی توسط کدک مطرح شده باشد، NULL را برمی‌گرداند.

کدک‌های UTF-16¶

این‌ها API‌های کدک UTF-16 هستند:

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶

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

کدگشایی size بایت از یک رشته بافر کدگذاری‌شده با UTF-16 انجام می‌دهد و شیء یونیکد متناظر را برمی‌گرداند. errors (در صورت NULL نبودن) مدیریت خطا را تعیین می‌کند. مقدار پیش‌فرض آن "strict" است.

اگر byteorder غیر از NULL باشد، کدگشا کدگشایی را با استفاده از ترتیب بایت داده‌شده آغاز می‌کند:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

اگر *byteorder صفر باشد و دو بایت نخست داده‌های ورودی، یک نشانگر ترتیب بایت (BOM) باشند، کدگشا به این ترتیب بایت تغییر می‌کند و BOM در رشته یونیکدی حاصل کپی نمی‌شود. اگر *byteorder برابر -1 یا 1 باشد، هر نشانگر ترتیب بایتی به خروجی کپی می‌شود (که در آن به یک نویسه‌ی \ufeff یا \ufffe تبدیل خواهد شد).

پس از تکمیل، *byteorder به ترتیب بایت جاری در انتهای داده‌های ورودی تنظیم می‌شود.

اگر byteorder برابر NULL باشد، کدک در حالت ترتیب بومی آغاز می‌کند.

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

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶

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

اگر consumed برابر با NULL باشد، مانند PyUnicode_DecodeUTF16() رفتار می‌کند. اگر consumed برابر با NULL نباشد، PyUnicode_DecodeUTF16Stateful() دنباله‌های بایت ناقص انتهایی UTF-16 (مانند تعداد فردی از بایت‌ها یا یک جفت جانشین جداشده) را به‌عنوان خطا در نظر نمی‌گیرد. این بایت‌ها کدگشایی نمی‌شوند و تعداد بایت‌هایی که کدگشایی شده‌اند در consumed ذخیره خواهد شد.

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)¶

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

یک رشته بایت پایتون را با استفاده از کدگذاری UTF-16 در ترتیب بایت بومی برمی‌گرداند. این رشته همیشه با نشانگر ترتیب بایت (BOM) آغاز می‌شود. برخورد با خطا «strict» است. اگر توسط کدک استثنایی مطرح شده باشد، NULL را برمی‌گرداند.

کدک‌های UTF-7¶

این‌ها API‌های کدک UTF-7 هستند:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)¶

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

با کدگشایی size بایت از رشته‌ی str که با UTF-7 کدگذاری شده است، یک شیء یونیکد ایجاد می‌کند. در صورتی که استثنایی از سوی کدک مطرح شده باشد، NULL را برمی‌گرداند.

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

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

اگر consumed برابر NULL باشد، مانند PyUnicode_DecodeUTF7() رفتار می‌کند. اگر consumed برابر NULL نباشد، بخش‌های ناقص پایانی base-64 در UTF-7 به‌عنوان خطا تلقی نمی‌شوند. این بایت‌ها کدگشایی نمی‌شوند و تعداد بایت‌هایی که کدگشایی شده‌اند در consumed ذخیره می‌شود.

کدک‌های Unicode-Escape¶

این‌ها API‌های کدک «Unicode Escape» هستند:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶

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

با کدگشایی size بایت از رشته str که با Unicode-Escape کدگذاری شده است، یک شیء یونیکد ایجاد می‌کند. اگر استثنایی توسط کدک مطرح شده باشد، NULL را برمی‌گرداند.

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶

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

یک شیء یونیکد را با استفاده از Unicode-Escape کدگذاری می‌کند و نتیجه را به‌صورت یک شیء بایت برمی‌گرداند. مدیریت خطا "strict" است. اگر کدک استثنایی پرتاب کرده باشد، NULL برمی‌گرداند.

کدک‌های Raw-Unicode-Escape¶

این‌ها API‌های کدک «Raw Unicode Escape» هستند:

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶

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

با کدگشایی size بایت از رشته‌ی str کدگذاری‌شده با Raw-Unicode-Escape، یک شیء یونیکد ایجاد می‌کند. اگر استثنایی توسط کدک ایجاد شده باشد، NULL برمی‌گرداند.

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶

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

یک شیء یونیکد را با استفاده از Raw-Unicode-Escape کدگذاری کرده و نتیجه را به‌صورت یک شیء بایت برمی‌گرداند. مدیریت خطا «strict» است. در صورت ایجاد استثنا توسط کدک، NULL برگردانده می‌شود.

کدک‌های Latin-1¶

این‌ها API‌های کدک Latin-1 هستند: Latin-1 با نخستین ۲۵۶ مقدار ترتیبی یونیکد مطابقت دارد و کدک‌ها هنگام کدگذاری تنها همین مقادیر را می‌پذیرند.

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)¶

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

با کدگشایی size بایت از رشته‌ی str کدگذاری‌شده با Latin-1، یک شیء یونیکد ایجاد می‌کند. اگر کدک استثنایی ایجاد کرده باشد، NULL را برمی‌گرداند.

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶

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

شیء یونیکد را با استفاده از Latin-1 کدگذاری می‌کند و نتیجه را به‌صورت شیء بایت پایتون برمی‌گرداند. رسیدگی به خطا «strict» است. اگر استثنایی توسط کدک مطرح شده باشد، NULL برمی‌گرداند.

کدک‌های اسکی¶

این‌ها APIهای کدک اسکی هستند. فقط داده‌های اسکی ۷-بیتی پذیرفته می‌شوند. تمامی کدهای دیگر خطا ایجاد می‌کنند.

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)¶

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

یک شیء یونیکد را با کدگشایی size بایت از رشته‌ی کدگذاری‌شده‌ی اسکی str ایجاد کنید. اگر کدک استثنایی ایجاد کرده باشد، NULL را برگردانید.

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶

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

یک شیء یونیکد را با استفاده از اسکی کدگذاری کرده و نتیجه را به‌صورت شیء بایت پایتون برمی‌گرداند. مدیریت خطا «strict» است. اگر کدک استثنایی ایجاد کند، NULL را برمی‌گرداند.

کدک‌های نگاشت نویسه¶

این کدک از این نظر خاص است که می‌توان از آن برای پیاده‌سازی بسیاری از کدک‌های مختلف استفاده کرد (و در واقع همین کار برای به دست آوردن اکثر کدک‌های استاندارد موجود در بسته‌ی encodings انجام شده است). این کدک برای کدگذاری و کدگشایی نویسه‌ها از نگاشت‌ها استفاده می‌کند. شیءهای نگاشتی ارائه‌شده باید از رابط نگاشت __getitem__() پشتیبانی کنند؛ دیکشنری‌ها و دنباله‌ها به‌خوبی کار می‌کنند.

این‌ها APIهای کدک‌های نگاشتی هستند:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)¶

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

با کدگشایی size بایت از رشته‌ی کدگذاری‌شده‌ی str با استفاده از شیء نگاشت mapping داده‌شده، یک شیء یونیکد ایجاد می‌کند. اگر کدک استثنایی پرتاب کند، NULL را برمی‌گرداند.

اگر mapping برابر NULL باشد، کدگشایی Latin-1 اعمال خواهد شد. در غیر این صورت، mapping باید مقادیر ترتیبی بایت‌ها (اعداد صحیح در بازه‌ی ۰ تا ۲۵۵) را به رشته‌های یونیکد، اعداد صحیح (که سپس به عنوان مقادیر ترتیبی یونیکد تفسیر می‌شوند) یا None نگاشت کند. بایت‌های داده‌ی نگاشت‌نشده -- بایت‌هایی که موجب LookupError می‌شوند و همچنین بایت‌هایی که به None، 0xFFFE یا '\ufffe' نگاشت می‌شوند -- به عنوان نگاشت‌های تعریف‌نشده در نظر گرفته می‌شوند و باعث خطا می‌شوند.

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)¶

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

یک شیء یونیکد را با استفاده از شیء نگاشت داده‌شده کدگذاری می‌کند و نتیجه را به‌صورت یک شیء بایت برمی‌گرداند. مدیریت خطا «strict» است. اگر کدک استثنایی ایجاد کرده باشد، NULL برمی‌گرداند.

شیء نگاشت باید اعداد صحیح ترتیبی یونیکد را به اشیاء بایت، اعداد صحیح در بازه‌ی ۰ تا ۲۵۵ یا None نگاشت کند. شماره‌های ترتیبی نویسه‌های نگاشت‌نشده (همان‌هایی که باعث LookupError می‌شوند) و همچنین آن‌هایی که به None نگاشت شده‌اند، به‌عنوان «نگاشت تعریف‌نشده» در نظر گرفته می‌شوند و باعث خطا می‌شوند.

API کدک زیر از این جهت ویژه است که یونیکد را به یونیکد نگاشت می‌کند.

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)¶

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

یک رشته را با اعمال جدول نگاشت نویسه بر روی آن ترجمه می‌کند و شیء یونیکد حاصل را برمی‌گرداند. اگر کدک استثنا را پرتاب کرده باشد، NULL برمی‌گرداند.

جدول نگاشت باید اعداد صحیح ترتیبی یونیکد را به اعداد صحیح ترتیبی یونیکد یا None (که باعث حذف نویسه می‌شود) نگاشت کند.

برای جدول‌های نگاشت، تنها ارائه رابط __getitem__() کافی است؛ دیکشنری‌ها و دنباله‌ها به‌خوبی کار می‌کنند. ترتیبی‌های نگاشت‌نشده‌ی نویسه‌ها (آن‌هایی که باعث LookupError می‌شوند) دست‌نخورده باقی می‌مانند و به همان صورت کپی می‌شوند.

errors برای کدک‌ها معنای متداول خود را دارد. ممکن است NULL باشد که نشان می‌دهد از مدیریت خطای پیش‌فرض استفاده شود.

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

این‌ها APIهای کدک MBCS هستند. آن‌ها در حال حاضر فقط در ویندوز در دسترس هستند و از مبدل‌های MBCS در Win32 برای پیاده‌سازی تبدیل‌ها استفاده می‌کنند. توجه داشته باشید که MBCS (یا DBCS) دسته‌ای از کدگذاری‌هاست، نه فقط یک کدگذاری. کدگذاری مقصد توسط تنظیمات کاربر روی رایانه‌ای که کدک روی آن اجرا می‌شود تعریف می‌شود.

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)¶

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

با کدگشایی size بایت از رشته‌ی کدگذاری‌شده‌ی MBCS با نام str، یک شیء یونیکد ایجاد می‌کند. اگر کدک استثنایی مطرح کرده باشد، NULL برمی‌گرداند.

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

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

اگر consumed برابر NULL باشد، رفتاری مانند PyUnicode_DecodeMBCS() خواهد داشت. اگر consumed برابر NULL نباشد، PyUnicode_DecodeMBCSStateful() بایت پیشروی انتهایی (trailing lead byte) را کدگشایی نمی‌کند و تعداد بایت‌هایی که کدگشایی شده‌اند در consumed ذخیره می‌شود.

PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶

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

مشابه PyUnicode_DecodeMBCSStateful()، با این تفاوت که از صفحه کد مشخص‌شده توسط code_page استفاده می‌کند.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶

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

یک شیء یونیکد را با استفاده از MBCS کدگذاری می‌کند و نتیجه را به‌صورت شیء بایت پایتون برمی‌گرداند. مدیریت خطا «strict» است. اگر استثنایی توسط کدک ایجاد شده باشد، NULL برمی‌گرداند.

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶

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

شیء یونیکد را با استفاده از صفحه کد مشخص‌شده کدگذاری کرده و یک شیء بایت پایتون را برمی‌گرداند. اگر کدک استثنایی مطرح کرده باشد، NULL برمی‌گرداند. برای گرفتن کدگذار MBCS از صفحه کد CP_ACP استفاده کنید.

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