اشیاء بایت

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

بافر داخلی PyBytesObject همیشه یک بایت خالی (null) اضافی در پایان برای سازگاری با رشته‌های C خاتمه‌یافته‌به‌خالی (null terminated) شامل می‌شود. این بایت اضافی در PyBytes_Size() و نه در آرگومان‌های مختلف length و size توابع زیر شمارش می‌شود.

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: Use the PyBytesWriter API instead of PyBytes_FromStringAndSize(NULL, len).

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 پلتفرم تولید می‌کند.

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

[1] (1,2,3,4,5,6,7,8)

برای مشخص‌کننده‌های عدد صحیح (d, u, ld, lu, zd, zu, i, x): پرچم تبدیل 0 حتی هنگامی که دقتی مشخص‌شده باشد، تأثیر دارد.

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.

Resize a bytes object. newsize will be the new length of the bytes object. You can think of it as creating a new bytes object and destroying the old one, only more efficiently.

Pass the address of an existing bytes object as an lvalue (it may be written into), and the new size desired. On success, *bytes holds the resized bytes object and 0 is returned; the address in *bytes may differ from its input value. If the reallocation fails, the original bytes object at *bytes is deallocated, *bytes is set to NULL, MemoryError is set, and -1 is returned.

While bytes objects are usually immutable in Python, this special C API allows mutating a bytes object in-place. The returned bytes object can still be mutated using PyBytes_AsString(); except if newsize is zero in which case it returns the immutable empty bytes string.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.15: Use the PyBytesWriter API instead.

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

The PyBytesWriter API can be used to create a Python bytes object.

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

type PyBytesWriter

A bytes writer object.

The API is not thread safe. To share a writer with multiple threads, a critical section or a lock is needed.

The instance must be destroyed by PyBytesWriter_Finish() on success, or PyBytesWriter_Discard() on error.

Create, Finish, Discard

PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)

Create a PyBytesWriter to write size bytes.

If size is greater than zero, allocate size bytes, and set the writer size to size. The caller is responsible to write size bytes using PyBytesWriter_GetData(). This function does not overallocate.

On error, set an exception and return NULL.

size must be positive or zero.

PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)

Finish a PyBytesWriter created by PyBytesWriter_Create().

On success, return a Python bytes object. On error, set an exception and return NULL.

The writer instance is invalid after the call in any case. No API can be called on the writer after PyBytesWriter_Finish().

PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)

Similar to PyBytesWriter_Finish(), but resize the writer to size bytes before creating the bytes object.

PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)

Similar to PyBytesWriter_Finish(), but resize the writer using buf pointer before creating the bytes object.

Set an exception and return NULL if buf pointer is outside the internal buffer bounds.

Function pseudo-code:

Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer);
return PyBytesWriter_FinishWithSize(writer, size);

void PyBytesWriter_Discard(PyBytesWriter *writer)

Discard a PyBytesWriter created by PyBytesWriter_Create().

Do nothing if writer is NULL.

The writer instance is invalid after the call. No API can be called on the writer after PyBytesWriter_Discard().

High-level API

int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)

Grow the writer internal buffer by size bytes, write size bytes of bytes at the writer end, and add size to the writer size.

If size is equal to -1, call strlen(bytes) to get the string length.

On success, return 0. On error, set an exception and return -1.

int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)

Similar to PyBytes_FromFormat(), but write the output directly at the writer end. Grow the writer internal buffer on demand. Then add the written size to the writer size.

On success, return 0. On error, set an exception and return -1.

Getters

Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)

Get the writer size.

The function does not invalidate pointers returned by PyBytesWriter_GetData().

The function cannot fail.

void *PyBytesWriter_GetData(PyBytesWriter *writer)

Get the writer data: start of the internal buffer.

The pointer remains valid until a PyBytesWriter function other than PyBytesWriter_GetData() or PyBytesWriter_GetSize() is called on writer.

The function cannot fail.

Low-level API

int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)

Resize the writer to size bytes. It can be used to enlarge or to shrink the writer. This function typically overallocates to achieve amortized performance when resizing multiple times.

Newly allocated bytes are left uninitialized.

On success, return 0. On error, set an exception and return -1.

size must be positive or zero.

int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)

Resize the writer by adding grow bytes to the current writer size. This function typically overallocates to achieve amortized performance when resizing multiple times.

Newly allocated bytes are left uninitialized.

On success, return 0. On error, set an exception and return -1.

grow can be negative to shrink the writer.

void *PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)

Similar to PyBytesWriter_Grow(), but update also the buf pointer.

The buf pointer is moved if the internal buffer is moved in memory. The buf relative position within the internal buffer is left unchanged.

On error, set an exception and return NULL.

buf must not be NULL.

Function pseudo-code:

Py_ssize_t pos = (char*)buf - (char*)PyBytesWriter_GetData(writer);
if (PyBytesWriter_Grow(writer, size) < 0) {
    return NULL;
}
return (char*)PyBytesWriter_GetData(writer) + pos;