اشیاء بایت¶

این توابع هنگامی که انتظار پارامتر bytes را دارند و با پارامتری غیر bytes فراخوانی می‌شوند، TypeError را raise می‌کنند.

type PyBytesObject¶

این زیرنوع از PyObject یک شیء bytes پایتون را نمایش می‌دهد.

PyTypeObject PyBytes_Type¶

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

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

int PyBytes_Check(PyObject *o)¶

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

int PyBytes_CheckExact(PyObject *o)¶

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

PyObject *PyBytes_FromString(const char *v)¶

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

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

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)¶

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

در صورت موفقیت، شیء بایت جدیدی برمی‌گرداند که مقدار آن رونوشتی از رشته v و طول آن len است و در صورت شکست NULL برمی‌گرداند. اگر v برابر NULL باشد، محتویات شیء بایت مقداردهی‌نشده هستند.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: به جای PyBytes_FromStringAndSize(NULL, len) از API مربوط به PyBytesWriter استفاده کنید.

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

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

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

نویسه‌های قالب	نوع	کامنت
%%	غیرقابل اعمال	نویسه‌ی لفظی %.
%c	int	یک بایت منفرد که به‌صورت int در C بازنمایی می‌شود.
%d	int	معادل printf("%d") است. [1]
%u	unsigned int	معادل printf("%u") است. [1]
%ld	long	معادل printf("%ld"). [1]
%lu	unsigned long	معادل printf("%lu"). [1]
%zd	Py_ssize_t	معادل printf("%zd") است. [1]
%zu	size_t	معادل printf("%zu") است. [1]
%i	int	معادل printf("%i") است. [1]
%x	int	معادل printf("%x") است. [1]
%s	const char*	آرایه‌ی نویسه‌ای C که با نویسه‌ی تهی پایان می‌یابد.
%p	const void*	نمایش اشاره‌گر C در مبنای شانزده. عمدتاً معادل printf("%p") است، با این تفاوت که شروع آن با مقدار لفظی 0x تضمین شده است، صرف‌نظر از آنچه printf پلتفرم تولید می‌کند.

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

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

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

یکسان با PyBytes_FromFormat() است، به‌جز اینکه دقیقاً دو آرگومان می‌پذیرد.

PyObject *PyBytes_FromObject(PyObject *o)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

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

نکته

اگر شیء پروتکل بافر را پیاده‌سازی کند، بافر نباید در حین ایجاد شدن شیء بایت تغییر داده شود.

Py_ssize_t PyBytes_Size(PyObject *o)¶

قسمتی از ABI پایدار. Thread safety: Atomic.

طول بایت‌های شیء بایت o را برمی‌گرداند.

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)¶

Thread safety: Atomic.

مشابه PyBytes_Size()، اما بدون بررسی خطا.

char *PyBytes_AsString(PyObject *o)¶

قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

اشاره‌گری به محتویات o را برمی‌گرداند. این اشاره‌گر به بافر داخلی o اشاره می‌کند که از len(o) + 1 بایت تشکیل شده است. آخرین بایت در بافر همیشه تهی است، صرف‌نظر از اینکه بایت‌های تهی دیگری وجود دارند یا نه. این داده نباید به هیچ شکلی تغییر داده شود، مگر اینکه شیء تازه با استفاده از PyBytes_FromStringAndSize(NULL, size) ایجاد شده باشد. نباید آزادسازی شود. اگر o اصلاً یک شیء بایت نباشد، PyBytes_AsString() مقدار NULL را برمی‌گرداند و استثنای TypeError را ایجاد می‌کند.

char *PyBytes_AS_STRING(PyObject *string)¶

Thread safety: Safe to call from multiple threads with external synchronization only.

مشابه PyBytes_AsString()، اما بدون بررسی خطا.

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)¶

قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

محتوای شیء obj را که با تهی پایان یافته است، از طریق متغیرهای خروجی buffer و length برمی‌گرداند. در صورت موفقیت 0 را برمی‌گرداند.

اگر length برابر NULL باشد، شیء بایت نباید شامل بایت‌های تهی تعبیه‌شده باشد؛ در غیر این صورت، تابع -1 را برمی‌گرداند و استثنای ValueError به‌وجود می‌آید.

بافر به بافر داخلی obj اشاره می‌کند که شامل یک بایت تهی اضافی در انتها است (که در length شمرده نمی‌شود). داده‌ها نباید به هیچ شکلی تغییر داده شوند، مگر آنکه شیء به‌تازگی با استفاده از PyBytes_FromStringAndSize(NULL, size) ایجاد شده باشد. این بافر نباید آزاد شود. اگر obj اصلاً یک شیء بایت نباشد، PyBytes_AsStringAndSize() مقدار -1 را برمی‌گرداند و استثنای TypeError را ایجاد می‌کند.

تغییر یافته در نسخه‌ی 3.5: پیش‌تر، هنگامی که به بایت‌های تهی تعبیه‌شده در شیء بایت برخورد می‌شد، TypeError رخ می‌داد.

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)¶

قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

یک شیء بایت جدید در *bytes ایجاد می‌کند که شامل محتوای newpart الحاق‌شده به bytes است؛ فراخوان‌کننده مالک ارجاع جدید خواهد بود. ارجاع به مقدار قبلی bytes «دزدیده‌شده (stolen)» خواهد بود. اگر نتوان شیء جدید را ایجاد کرد، ارجاع قبلی به bytes همچنان «دزدیده‌شده» خواهد بود، مقدار *bytes برابر NULL قرار خواهد گرفت و استثنای مناسب تنظیم خواهد شد.

نکته

اگر newpart پروتکل بافر را پیاده‌سازی کرده باشد، بافر نباید در حین ایجاد شدن شیء بایت جدید تغییر کند.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)¶

قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

یک شیء بایت جدید در *bytes ایجاد می‌کند که محتوای newpart الحاق‌شده به bytes را در بر دارد. این نسخه ارجاع قوی به newpart را آزاد می‌کند (یعنی شمارش ارجاع آن را کاهش می‌دهد).

نکته

اگر newpart پروتکل بافر را پیاده‌سازی کرده باشد، بافر نباید در حین ایجاد شدن شیء بایت جدید تغییر کند.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)¶

Thread safety: Safe for concurrent use on the same object.

مشابه sep.join(iterable) در پایتون.

sep باید یک شیء bytes پایتون باشد. (توجه داشته باشید که PyUnicode_Join() جداکننده NULL را می‌پذیرد و آن را به‌عنوان یک فاصله در نظر می‌گیرد، در حالی که PyBytes_Join() جداکننده NULL را نمی‌پذیرد.)

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

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

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

نکته

اگر اشیاء iterable پروتکل بافر را پیاده‌سازی کنند، بافرها نباید در حین ایجاد شیء بایت جدید تغییر داده شوند.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)¶

Thread safety: Safe to call without external synchronization on distinct objects.

اندازه یک شیء بایت را تغییر می‌دهد. newsize طول جدید شیء بایت خواهد بود. می‌توانید آن را به‌صورت ایجاد یک شیء بایت جدید و نابود کردن شیء قدیمی تصور کنید، فقط با کارایی بیشتر. آدرس یک شیء بایت موجود را به‌عنوان یک چپ‌مقدار (lvalue) (که ممکن است در آن نوشته شود) به همراه اندازه جدید موردنظر ارسال کنید. در صورت موفقیت، *bytes حاوی شیء بایت با اندازه جدید است و 0 بازگردانده می‌شود؛ آدرس موجود در *bytes ممکن است با مقدار ورودی آن متفاوت باشد. اگر تخصیص مجدد شکست بخورد، شیء بایت اصلی موجود در *bytes آزاد می‌شود، *bytes برابر NULL قرار می‌گیرد، MemoryError تنظیم می‌شود و -1 بازگردانده می‌شود.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: به جای آن از API مربوط به PyBytesWriter استفاده کنید.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)¶

قسمتی از ABI پایدار. Thread safety: Atomic.

بازنمایی رشته‌ای bytes را برمی‌گرداند. این تابع در حال حاضر برای پیاده‌سازی bytes.__repr__() در پایتون استفاده می‌شود.

این تابع بررسی نوع انجام نمی‌دهد؛ گذراندن bytes به‌عنوان یک شیء غیربایتی یا NULL رفتار تعریف‌نشده است.

اگر smartquotes درست باشد، نمایش در صورت وجود علامت‌های نقل‌قول تکی در bytes، به‌جای رشته‌ی محصور در علامت نقل‌قول تکی از رشته‌ی محصور در علامت نقل‌قول دوتایی استفاده خواهد کرد. برای مثال، رشته‌ی بایتی 'Python' هنگامی که smartquotes درست باشد به‌صورت b"'Python'" و هنگامی که نادرست باشد به‌صورت b'\'Python\'' نمایش داده می‌شود.

در صورت موفقیت، این تابع یک ارجاع قوی به یک شیء str حاوی نمایش را برمی‌گرداند. در صورت شکست، این تابع NULL را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)¶

قسمتی از ABI پایدار. Thread safety: Atomic.

رشته‌ی خنثی‌شده با بک‌اسلش s را بازگشایی (unescape) کنید. s نباید NULL باشد. len باید اندازه‌ی s باشد.

errors باید یکی از "strict"، "replace" یا "ignore" باشد. اگر errors برابر NULL باشد، به‌طور پیش‌فرض از "strict" استفاده می‌شود.

در صورت موفقیت، این تابع یک ارجاع قوی به یک شیء bytes پایتونی حاوی رشته‌ی گریز‌زدایی‌شده (unescaped) را برمی‌گرداند. در صورت شکست، این تابع NULL را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.9: unicode و recode_encoding اکنون استفاده نمی‌شوند.

PyBytesWriter¶

رابط برمکی (API) نوع PyBytesWriter را می‌توان برای ایجاد یک شیء bytes در پایتون استفاده کرد.

type PyBytesWriter¶

یک نمونه‌ی نویسنده‌ی بایت (bytes writer).

این API امن برای چندنخی (thread-safe) نیست. برای اشتراک‌گذاری یک نویسنده با چندین نخ، یک بخش بحرانی (critical section) یا یک قفل مورد نیاز است.

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

PyObject* create_abc(void)
{
    PyBytesWriter *writer = PyBytesWriter_Create(3);
    if (writer == NULL) {
        return NULL;
    }

    char *str = PyBytesWriter_GetData(writer);
    memcpy(str, "abc", 3);
    return PyBytesWriter_Finish(writer);
}

PyObject* create_abc_ptr(void)
{
    PyBytesWriter *writer = PyBytesWriter_Create(3);
    if (writer == NULL) {
        return NULL;
    }

    char *str = PyBytesWriter_GetData(writer);
    memcpy(str, "abc", 3);
    str += 1;
    return PyBytesWriter_FinishWithPointer(writer, str);
}

int copy_bytes(char *dest, const char *src, Py_ssize_t num_bytes)
{
    ...
}

PyObject* create_string(const char *start, Py_ssize_t num_bytes)
{
    PyObject *result = PyBytes_FromStringAndSize(NULL, num_bytes);
    if (result == NULL) {
        return NULL;
    }
    if (copy_bytes(PyBytes_AS_STRING(result), start, num_bytes) < 0) {
        Py_CLEAR(result);
    }
    return result;
}

PyObject* create_string(const char *start, Py_ssize_t num_bytes)
{
    PyBytesWriter *writer = PyBytesWriter_Create(num_bytes);
    if (writer == NULL) {
        return NULL;
    }
    if (copy_bytes(PyBytesWriter_GetData(writer), start, num_bytes) < 0) {
        PyBytesWriter_Discard(writer);
        return NULL;
    }
    return PyBytesWriter_Finish(writer);
}

void create_string(Py_ssize_t size)
{
    PyObject *bytes = PyBytes_FromStringAndSize(NULL, size);
    if (bytes == NULL) {
        return NULL;
    }
    char *str = PyBytes_AS_STRING(bytes);

    // ... write data into str ...

    if (_PyBytes_Resize(&bytes, (str - PyBytes_AS_STRING(bytes)))) {
        return NULL;
    }
    return bytes;
}

void create_string(Py_ssize_t size)
{
    PyBytesWriter *writer = PyBytesWriter_Create(size);
    if (writer == NULL) {
        return NULL;
    }
    char *str = PyBytesWriter_GetData(writer);

    // ... write data into str ...

    return PyBytesWriter_FinishWithPointer(writer, str;
}