اشیاء یونیکد و کدک‌ها¶

اشیاء یونیکد¶

از زمان پیاده‌سازی PEP 393 در پایتون 3.3، شیءهای یونیکد به‌طور داخلی از نمایش‌های گوناگونی استفاده می‌کنند تا امکان مدیریت کل بازه‌ی نویسه‌های یونیکد فراهم شود و در عین حال از نظر حافظه بهره‌ور باقی بمانند. برای رشته‌هایی که تمام نقطه‌کدهای آن‌ها کمتر از ۱۲۸، ۲۵۶ یا ۶۵۵۳۶ است، حالت‌های خاصی وجود دارد؛ در غیر این صورت، نقطه‌کدها باید کمتر از ۱۱۱۴۱۱۲ باشند (که بازه‌ی کامل یونیکد است).

بازنمایی UTF-8 به‌هنگام نیاز ایجاد می‌شود و در نهانگاه شیء یونیکد ذخیره می‌شود.

توجه

نمایش Py_UNICODE از پایتون 3.12 همراه با APIهای منسوخ حذف شده است. برای اطلاعات بیشتر به PEP 623 مراجعه کنید.

نوع یونیکد¶

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

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() به دست آمده است) می‌خواند. هیچ بررسی یا فراخوانی ready انجام نمی‌شود.

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

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶: یک نویسه از شیء یونیکد unicode می‌خواند که باید در نمایش «کانونیکال» باشد. اگر چندین خواندن متوالی انجام می‌دهید، این کارایی کمتری نسبت به PyUnicode_READ() دارد.

اضافه شده در نسخه‌ی 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.

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

یونیکد ویژگی‌های نویسه‌ی متعدد و گوناگونی را فراهم می‌کند. پرکاربردترین آن‌ها از طریق این ماکروها در دسترس‌اند که بسته به پیکربندی پایتون به توابع 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).

اضافه شده در نسخه‌ی 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 باشند و دقیقاً با نویسه‌های قالب در رشته قالب کدگذاری‌شده با اسکی مطابقت داشته باشند.

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

نویسه‌ی '%' که آغاز مشخص‌کننده را علامت‌گذاری می‌کند.
پرچم‌های تبدیل (اختیاری) که بر نتیجه‌ی برخی از نوع‌های تبدیل تأثیر می‌گذارند.
حداقل عرض میدان (اختیاری). اگر به‌صورت '*' (ستاره) مشخص شود، عرض واقعی در آرگومان بعدی داده می‌شود که باید از نوع int باشد، و شیئی که باید تبدیل شود، پس از حداقل عرض میدان و دقت اختیاری قرار می‌گیرد.
دقت (اختیاری)، به‌صورت '.' (نقطه) و به دنبال آن مقدار دقت داده می‌شود. اگر به‌صورت '*' (ستاره) تعیین شود، دقت واقعی در آرگومان بعدی داده می‌شود که باید از نوع int باشد، و مقداری که باید تبدیل شود پس از دقت می‌آید.
اصلاح‌کننده‌ی طول (اختیاری).
نوع تبدیل.

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

پرچم	معنا
`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 را همراه با استثنای تنظیم‌شده برمی‌گرداند.

اضافه شده در نسخه‌ی 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 را مطرح می‌کند.

کدک‌های توکار¶

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

بسیاری از API‌های زیر دو آرگومان encoding و errors دریافت می‌کنند و معناشناسی این آرگومان‌ها با معناشناسی آرگومان‌های سازنده‌ی شیء رشته‌ی توکار str() یکسان است.

تنظیم کدگذاری به NULL باعث می‌شود از کدگذاری پیش‌فرض که UTF-8 است استفاده شود. فراخوانی‌های سامانه فایل‌بندی باید برای کدگذاری نام پرونده‌ها از PyUnicode_FSConverter() استفاده کنند. این تابع به‌طور داخلی از کدگذاری سامانه فایل‌بندی و هندلر خطا استفاده می‌کند.

رسیدگی به خطا توسط errors تنظیم می‌شود که ممکن است به NULL نیز تنظیم شود، به این معنا که از رسیدگی پیش‌فرض تعریف‌شده برای کدک استفاده شود. رسیدگی پیش‌فرض به خطا برای همه‌ی کدک‌های توکار "strict" است (استثنای 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.

متدها و توابع جایگاهی¶

APIهای زیر می‌توانند اشیاء یونیکد و رشته‌ها را در ورودی مدیریت کنند (در توضیحات، آن‌ها را رشته می‌نامیم) و بسته به مورد، شیء یونیکد یا عدد صحیح برمی‌گردانند.

همگی در صورت وقوع استثنا NULL یا -1 را برمی‌گردانند.

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
دو رشته را الحاق می‌کند و یک رشته یونیکد جدید به دست می‌دهد.

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

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

یک رشته را تقسیم می‌کند و فهرستی از رشته‌های یونیکد به دست می‌دهد. اگر sep برابر NULL باشد، تقسیم در تمام زیررشته‌های فضای سفید انجام می‌شود. در غیر این صورت، تقسیم‌ها در جداکننده‌ی داده‌شده رخ می‌دهند. حداکثر maxsplit تقسیم انجام می‌شود. اگر منفی باشد، هیچ محدودیتی تعیین نمی‌شود. جداکننده‌ها در فهرست حاصل قرار نمی‌گیرند.

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

معادل str.split() است.

PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

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

مشابه PyUnicode_Split() است، اما تفکیک از انتهای رشته آغاز خواهد شد.

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

معادل str.rsplit() است.

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
یک رشته یونیکد را در شکست‌های سطر تفکیک می‌کند و فهرستی از رشته‌های یونیکد برمی‌گرداند. CRLF به عنوان یک شکست سطر در نظر گرفته می‌شود. اگر keepends برابر 0 باشد، نویسه‌های شکست سطر در رشته‌های حاصل گنجانده نمی‌شوند.

PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)¶

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

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

sep نباید خالی باشد.

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

معادل با str.partition() است.

PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)¶

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

مشابه PyUnicode_Partition() است، اما یک رشته‌ی یونیکد را در آخرین رخداد sep جدا می‌کند. اگر جداکننده یافت نشود، یک تاپل سه‌تایی شامل دو رشته‌ی خالی و سپس خودِ رشته را برمی‌گرداند.

sep نباید خالی باشد.

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

معادل str.rpartition() است.

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
دنباله‌ای از رشته‌ها را با استفاده از جداکننده‌ی داده‌شده الحاق کنید و رشته‌ی یونیکدی حاصل را برگردانید.

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: قسمتی از ABI پایدار.
اگر substr با unicode[start:end] در انتهای مشخص‌شده تطبیق داشته باشد، 1 را برمی‌گرداند (direction == -1 به معنای انجام تطبیق پیشوند و direction == 1 به معنای تطبیق پسوند است)، در غیر این صورت 0. در صورت وقوع خطا -1 برمی‌گرداند.

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: قسمتی از ABI پایدار.
اولین موقعیت substr در unicode[start:end] را با استفاده از direction داده‌شده برمی‌گرداند (direction == 1 به معنای انجام جستجوی رو به جلو و direction == -1 به معنای جستجوی رو به عقب است). مقدار بازگشتی اندیس اولین تطبیق است؛ مقدار -1 نشان می‌دهد که هیچ تطبیقی یافت نشد و -2 نشان می‌دهد که خطایی رخ داده و استثنایی تنظیم شده است.

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)¶: قسمتی از ABI پایدار از نسخه‌ی 3.7.
اولین موقعیت نویسه ch در unicode[start:end] را با استفاده از direction داده‌شده برمی‌گرداند (direction == 1 به معنای انجام جستجوی رو به جلو است و direction == -1 به معنای جستجوی رو به عقب). مقدار بازگشتی، اندیس اولین تطبیق است؛ مقدار -1 نشان می‌دهد که هیچ تطبیقی یافت نشد و -2 نشان می‌دهد که خطایی رخ داده و استثنایی تنظیم شده است.

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

تغییر یافته در نسخه‌ی 3.7: start و end اکنون به‌گونه‌ای تنظیم شده‌اند که مانند unicode[start:end] رفتار کنند.

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)¶: قسمتی از ABI پایدار.
تعداد رخدادهای بدون هم‌پوشانی substr در unicode[start:end] را برمی‌گرداند. در صورت وقوع خطا، -1 برگردانده می‌شود.

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
حداکثر maxcount تکرار از substr در unicode را با replstr جایگزین می‌کند و شیء یونیکد حاصل را برمی‌گرداند. maxcount == -1 به معنای جایگزینی همه‌ی تکرارها است.

int PyUnicode_Compare(PyObject *left, PyObject *right)¶

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

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

این تابع در صورت شکست -1 را برمی‌گرداند، بنابراین برای بررسی خطاها باید PyErr_Occurred() را فراخوانی کنید.

همچنین ملاحظه نمائید

تابع PyUnicode_Equal().

int PyUnicode_Equal(PyObject *a, PyObject *b)¶

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

آزمون کنید که آیا دو رشته برابرند:

اگر a برابر با b باشد، 1 را برمی‌گرداند.
اگر a برابر b نباشد، 0 را برمی‌گرداند.
اگر a یا b یک شیء str نباشد، یک استثنای TypeError تنظیم می‌شود و -1 برگردانده می‌شود.

اگر a و b شیءهای str باشند، این تابع همیشه با موفقیت اجرا می‌شود.

این تابع برای زیرکلاس‌های str کار می‌کند، اما متد سفارشی __eq__() را رعایت نمی‌کند.

همچنین ملاحظه نمائید

تابع PyUnicode_Compare().

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

int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)¶

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

یک شیء یونیکد را با یک بافر کاراکتری که به‌عنوان کدگذاری‌شده با UTF-8 یا اسکی تفسیر می‌شود، مقایسه می‌کند و در صورت برابری آن‌ها مقدار درست (1) و در غیر این صورت مقدار نادرست (0) را برمی‌گرداند. اگر شیء یونیکد شامل نقطه‌کدهای جانشین (U+D800 - U+DFFF) باشد یا رشته‌ی C یک UTF-8 معتبر نباشد، مقدار نادرست (0) برگردانده می‌شود.

این تابع هیچ استثنایی ایجاد نمی‌کند.

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

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)¶: قسمتی از ABI پایدار از نسخه‌ی 3.13.
مشابه PyUnicode_EqualToUTF8AndSize() است، اما طول string با استفاده از strlen() محاسبه می‌شود. اگر شیء یونیکد شامل نویسه‌های تهی باشد، مقدار نادرست (0) بازگردانده می‌شود.

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

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)¶

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

شیء یونیکد unicode را با string مقایسه می‌کند و به ترتیب برای کمتر از، برابر با و بزرگ‌تر از، -1، 0 و 1 را برمی‌گرداند. بهتر است فقط رشته‌های کدگذاری‌شده با اسکی ارسال شوند، اما تابع در صورتی که رشته ورودی شامل نویسه‌های غیراسکی باشد، آن را به عنوان ISO-8859-1 تفسیر می‌کند.

این تابع هیچ استثنایی ایجاد نمی‌کند.

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)¶

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

مقایسه غنی (rich compare) دو رشته یونیکد را انجام می‌دهد و یکی از موارد زیر را برمی‌گرداند:

NULL در صورتی که استثنایی رخ داده باشد
Py_True یا Py_False برای مقایسه‌های موفق
Py_NotImplemented در صورتی که ترکیب نوع‌ها نا‌شناخته باشد

مقادیر ممکن برای op عبارت‌اند از Py_GT، Py_GE، Py_EQ، Py_NE، Py_LT و Py_LE.

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
شیء رشته‌ی جدیدی از format و args برمی‌گرداند؛ این همانند format % args است.

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)¶

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

بررسی می‌کند که آیا substr در unicode موجود است و مطابق آن true یا false برمی‌گرداند.

substr باید به یک رشته یونیکدی تک‌عنصری تبدیل‌پذیر باشد. اگر خطایی رخ داده باشد، -1 بازگردانده می‌شود.

void PyUnicode_InternInPlace(PyObject **p_unicode)¶

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

آرگومان *p_unicode را به‌صورت درجا درون‌سازی (intern) می‌کند. این آرگومان باید نشانی یک متغیر اشاره‌گر باشد که به یک شیء رشته یونیکد پایتون اشاره کند. اگر رشته‌ای از پیش درونی‌سازی‌شده موجود باشد که با *p_unicode یکسان باشد، *p_unicode را برابر آن قرار می‌دهد (با آزاد کردن ارجاع به شیء رشته قدیمی و ایجاد یک ارجاع قوی جدید به شیء رشته درونی‌سازی‌شده)، در غیر این صورت *p_unicode را دست‌نخورده باقی می‌گذارد و آن را درون‌سازی می‌کند.

(توضیح: هرچند بحث‌های فراوانی درباره‌ی ارجاع‌ها مطرح می‌شود، این تابع را از نظر ارجاع خنثی در نظر بگیرید. باید مالک شیء‌ای که ارسال می‌کنید باشید؛ پس از فراخوانی، دیگر مالک ارجاعی که ارسال کرده‌اید نیستید، اما از این پس مالک نتیجه هستید.)

این تابع هرگز استثنایی ایجاد نمی‌کند. در صورت بروز خطا، آرگومان خود را بدون تغییر باقی می‌گذارد و آن را درون‌سازی (interning) نمی‌کند.

نمونه‌های زیرکلاس‌های str ممکن است درون‌سازی نشوند؛ به این معنا که PyUnicode_CheckExact(*p_unicode) باید درست باشد. اگر چنین نباشد، آرگومان — مانند هر خطای دیگر — بدون تغییر باقی می‌ماند.

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

PyObject *PyUnicode_InternFromString(const char *str)¶

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

ترکیبی از PyUnicode_FromString() و PyUnicode_InternInPlace()، که برای رشته‌های تخصیص‌یافته به‌صورت ایستا در نظر گرفته شده است.

بازگرداندن ارجاعی جدید (مالکانه — owned) به یک شیء رشته‌ی یونیکدی جدید که درون‌سازی (intern) شده است، یا به یک شیء رشته‌ی درونی‌سازی‌شده‌ی قبلی با همان مقدار.

پایتون ممکن است ارجاعی به نتیجه را نگه دارد، یا آن را نامیرا کند و در نتیجه مانع از زباله‌روبی به‌موقع آن شود. برای درونی‌سازی تعداد نامحدودی از رشته‌های متفاوت، مانند رشته‌هایی که از ورودی کاربر می‌آیند، ترجیح دهید PyUnicode_FromString() و PyUnicode_InternInPlace() را مستقیماً فراخوانی کنید.

unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)¶: اگر str درونی‌سازی‌شده باشد، مقدار غیرصفر و در غیر این صورت صفر را برمی‌گرداند. آرگومان str باید یک رشته باشد؛ این مورد بررسی نمی‌شود. این تابع همیشه با موفقیت اجرا می‌شود.

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

PyUnicodeWriter¶

از API PyUnicodeWriter می‌توان برای ایجاد یک شیء str پایتونی استفاده کرد.

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

type PyUnicodeWriter¶

یک نمونه‌ی نوشتارگر یونیکد.

نمونه باید در صورت موفقیت توسط PyUnicodeWriter_Finish() یا در صورت خطا توسط PyUnicodeWriter_Discard() نابود شود.

PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)¶

یک نمونه از نویسنده یونیکد ایجاد کنید.

length باید بزرگ‌تر یا مساوی 0 باشد.

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

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

PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)¶

شیء str نهایی پایتون را برمی‌گرداند و نمونه‌ی نویسنده را نابود می‌کند.

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

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

void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)¶

بافر داخلی یونیکد را دور می‌ریزد و نمونه‌ی نویسنده را نابود می‌کند.

اگر writer برابر NULL باشد، هیچ عملیاتی انجام نمی‌شود.

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

int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)¶

نویسه‌ی تکی یونیکد ch را در writer بنویسید.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

رشته str را از UTF-8 در حالت سخت‌گیرانه کدگشایی می‌کند و خروجی را در writer می‌نویسد.

size طول رشته بر حسب بایت است. اگر size برابر با -1 باشد، برای به دست آوردن طول رشته، strlen(str) فراخوانی می‌شود.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

همچنین ببینید PyUnicodeWriter_DecodeUTF8Stateful().

int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

رشته اسکی str را در writer بنویسید.

size طول رشته بر حسب بایت است. اگر size برابر با -1 باشد، برای به دست آوردن طول رشته، strlen(str) فراخوانی می‌شود.

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

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)¶

رشته پهن str را در writer می‌نویسد.

size تعداد نویسه‌های پهن است. اگر size برابر با -1 باشد، برای به‌دست آوردن طول رشته، wcslen(str) را فراخوانی کنید.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

int PyUnicodeWriter_WriteUCS4(PyUnicodeWriter *writer, Py_UCS4 *str, Py_ssize_t size)¶

رشته UCS4 str را در writer می‌نویسد.

size تعداد نویسه‌های UCS4 است.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)¶

PyObject_Str() را روی obj فراخوانی می‌کند و خروجی را در writer می‌نویسد.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

برای نوشتن یک زیرکلاس از str که متد __str__() را بازنویسی کند، می‌توان از PyUnicode_FromObject() برای به‌دست آوردن رشته اصلی استفاده کرد.

int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)¶

PyObject_Repr() را روی obj فراخوانی کنید و خروجی را در writer بنویسید.

اگر obj برابر NULL باشد، رشته‌ی "<NULL>" را در writer می‌نویسد.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.14.4: پشتیبانی از NULL افزوده شد.

int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)¶

زیررشته‌ی str[start:end] را در writer بنویسید.

str باید یک شیء str پایتون باشد. start باید بزرگ‌تر یا مساوی ۰ و کوچک‌تر یا مساوی end باشد. end باید کوچک‌تر یا مساوی طول str باشد.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)¶

مشابه PyUnicode_FromFormat()، اما خروجی را مستقیماً در writer می‌نویسد.

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

int PyUnicodeWriter_DecodeUTF8Stateful(PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)¶

رشته‌ی str را از UTF-8 با هندلر خطای errors کدگشایی می‌کند و خروجی را در writer می‌نویسد.

size طول رشته بر حسب بایت است. اگر size برابر با -1 باشد، برای به دست آوردن طول رشته، strlen(str) فراخوانی می‌شود.

errors نام یک هندلر خطا است، مانند "replace". اگر errors برابر NULL باشد، از هندلر خطای سخت‌گیرانه استفاده کنید.

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

در صورت موفقیت، 0 را برمی‌گرداند. در صورت خطا، یک استثنا تنظیم می‌کند، نوشتارگر را بدون تغییر باقی می‌گذارد و -1 را برمی‌گرداند.

همچنین PyUnicodeWriter_WriteUTF8() را ببینید.

API منسوخ¶

API زیر منسوخ شده است.

type Py_UNICODE¶: این یک تعریف نوع (typedef) از wchar_t است که بسته به پلتفرم، نوعی ۱۶ بیتی یا ۳۲ بیتی است. لطفاً به‌جای آن، مستقیماً از wchar_t استفاده کنید.

تغییر یافته در نسخه‌ی 3.3: در نسخه‌های قبلی، این یک نوع ۱۶بیتی یا ۳۲بیتی بود، بسته به اینکه شما در زمان ساخت، نسخه‌ی «باریک» یا «پهن» یونیکد پایتون را انتخاب کرده باشید.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد.

int PyUnicode_READY(PyObject *unicode)¶: هیچ کاری انجام ندهید و 0 را برگردانید. این API تنها برای سازگاری با نسخه‌های پیشین نگه داشته شده است، اما برنامه‌ای برای حذف آن وجود ندارد.

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

منسوخ شده از نسخه‌ی 3.10: این API از پایتون 3.12 به بعد هیچ کاری انجام نمی‌دهد. پیش‌تر، لازم بود برای هر رشته‌ای که با استفاده از API قدیمی (PyUnicode_FromUnicode() یا مشابه آن) ایجاد شده بود، فراخوانی شود.

unsigned int PyUnicode_IS_READY(PyObject *unicode)¶: هیچ کاری انجام نمی‌دهد و 1 را برمی‌گرداند. این API تنها برای سازگاری با نسخه‌های قبلی نگه داشته شده است، اما برنامه‌ای برای حذف آن وجود ندارد.

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

منسوخ شده از نسخه‌ی 3.14: این API از پایتون 3.12 به بعد هیچ کاری انجام نمی‌دهد. پیش‌تر، می‌شد آن را برای بررسی ضرورت PyUnicode_READY() فراخوانی کرد.

اشیاء یونیکد و کدک‌ها¶