اشیاء بایت¶
این توابع هنگامی که انتظار پارامتر bytes را دارند و با پارامتری غیر bytes فراخوانی میشوند، TypeError را raise میکنند.
بافر داخلی PyBytesObject همیشه یک بایت خالی (null) اضافی در پایان برای سازگاری با رشتههای C خاتمهیافتهبهخالی (null terminated) شامل میشود. این بایت اضافی در PyBytes_Size() و نه در آرگومانهای مختلف length و size توابع زیر شمارش میشود.
-
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 مطابقت داشته باشند. نویسههای قالب زیر مجاز هستند:نویسههای قالب
نوع
کامنت
%%غیرقابل اعمال
نویسهی لفظی %.
%cint
یک بایت منفرد که بهصورت int در C بازنمایی میشود.
%dint
معادل
printf("%d")است. [1]%uunsigned int
معادل
printf("%u")است. [1]%ldlong
معادل
printf("%ld"). [1]%luunsigned long
معادل
printf("%lu"). [1]%zdمعادل
printf("%zd")است. [1]%zusize_t
معادل
printf("%zu")است. [1]%iint
معادل
printf("%i")است. [1]%xint
معادل
printf("%x")است. [1]%sconst char*
آرایهی نویسهای C که با نویسهی تهی پایان مییابد.
%pconst 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 در پایتون استفاده کرد.
اضافه شده در نسخهی 3.15.
-
type PyBytesWriter¶
یک نمونهی نویسندهی بایت (bytes writer).
این API امن برای چندنخی (thread-safe) نیست. برای اشتراکگذاری یک نویسنده با چندین نخ، یک بخش بحرانی (critical section) یا یک قفل مورد نیاز است.
نمونه باید در صورت موفقیت توسط
PyBytesWriter_Finish()و در صورت بروز خطا توسطPyBytesWriter_Discard()نابود شود.
Create, Finish, Discard¶
-
PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)¶
ایجاد یک
PyBytesWriterبرای نوشتن size بایت.اگر size بزرگتر از صفر باشد، size بایت تخصیص دهید و اندازهی نویسنده را روی size تنظیم کنید. فراخواننده مسئول نوشتن size بایت با استفاده از
PyBytesWriter_GetData()است. این تابع تخصیص بیش از حد (overallocate) انجام نمیدهد.در صورت بروز خطا، یک استثنا تنظیم کرده و
NULLرا برگردانید.size باید مثبت یا صفر باشد.
-
PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)¶
پایان دادن به یک
PyBytesWriterکه توسطPyBytesWriter_Create()ایجاد شده است.در صورت موفقیت، یک شیء
bytesپایتون را برمیگرداند. در صورت بروز خطا، یک استثنا تنظیم کرده وNULLرا برگردانید.نمونهی نویسنده در هر صورت پس از این فراخوانی نامعتبر میشود. پس از
PyBytesWriter_Finish()هیچ API روی نویسنده قابل فراخوانی نیست.
-
PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)¶
مشابه
PyBytesWriter_Finish()، اما پیش از ایجاد شیءbytes، اندازهی نویسنده را به size بایت تغییر دهید.
-
PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)¶
مشابه
PyBytesWriter_Finish()، اما پیش از ایجاد شیءbytes، اندازهی نویسنده را با استفاده از اشارهگر buf تغییر دهید.اگر اشارهگر buf خارج از کرانهای بافر داخلی باشد، یک استثنا تنظیم کرده و
NULLرا برگردانید.کد شبه تابع (pseudo-code):
Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer); return PyBytesWriter_FinishWithSize(writer, size);
-
void PyBytesWriter_Discard(PyBytesWriter *writer)¶
دور انداختن یک
PyBytesWriterکه توسطPyBytesWriter_Create()ایجاد شده است.اگر writer برابر با
NULLباشد، هیچ کاری انجام ندهید.نمونهی نویسنده پس از این فراخوانی نامعتبر میشود. پس از
PyBytesWriter_Discard()هیچ API روی نویسنده قابل فراخوانی نیست.
API ردهبالا¶
-
int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)¶
بافر داخلی writer را به اندازهی size بایت بزرگ کنید، size بایت از bytes را در انتهای writer بنویسید و size را به اندازهی writer اضافه کنید.
اگر size برابر با
-1باشد، برای به دست آوردن طول رشتهstrlen(bytes)را فراخوانی کنید.در صورت موفقیت،
0را برمیگرداند. در صورت بروز خطا، یک استثنا تنظیم کرده و-1را برگردانید.
-
int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)¶
مشابه
PyBytes_FromFormat()، اما خروجی را مستقیماً در انتهای نویسنده مینویسد. بافر داخلی نویسنده را در صورت نیاز بزرگ کنید. سپس اندازهی نوشتهشده را به اندازهی نویسنده اضافه کنید.در صورت موفقیت،
0را برمیگرداند. در صورت بروز خطا، یک استثنا تنظیم کرده و-1را برگردانید.
getterها¶
-
Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)¶
اندازهی نویسنده را دریافت کنید.
این تابع اشارهگرهای بازگرداندهشده توسط
PyBytesWriter_GetData()را نامعتبر نمیکند.این تابع نمیتواند با خطا مواجه شود.
-
void *PyBytesWriter_GetData(PyBytesWriter *writer)¶
دادههای نویسنده را دریافت کنید: شروع بافر داخلی.
این اشارهگر تا زمانی که تابعی از
PyBytesWriterغیر ازPyBytesWriter_GetData()یاPyBytesWriter_GetSize()روی writer فراخوانی شود، معتبر باقی میماند.این تابع نمیتواند با خطا مواجه شود.
API سطح پایین¶
-
int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)¶
اندازهی نویسنده را به size بایت تغییر دهید. از آن میتوان برای بزرگ کردن یا کوچک کردن نویسنده استفاده کرد. این تابع معمولاً برای دستیابی به کارایی سرشکنشده هنگام تغییر اندازهی مکرر، حافظه را بیشتر تخصیص میدهد.
بایتهای تازه تخصیصیافته مقداردهی اولیه نمیشوند.
در صورت موفقیت،
0را برمیگرداند. در صورت بروز خطا، یک استثنا تنظیم کرده و-1را برگردانید.size باید مثبت یا صفر باشد.
-
int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)¶
با اضافه کردن grow بایت به اندازهی فعلی نویسنده، اندازهی آن را تغییر دهید. این تابع معمولاً برای دستیابی به کارایی سرشکنشده هنگام تغییر اندازهی مکرر، حافظه را بیشتر تخصیص میدهد.
بایتهای تازه تخصیصیافته مقداردهی اولیه نمیشوند.
در صورت موفقیت،
0را برمیگرداند. در صورت بروز خطا، یک استثنا تنظیم کرده و-1را برگردانید.مقدار grow میتواند منفی باشد تا نویسنده کوچک شود.
-
void *PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)¶
مشابه
PyBytesWriter_Grow()است، اما اشارهگر buf را نیز بهروزرسانی میکند.اگر بافر داخلی در حافظه جابهجا شود، اشارهگر buf نیز جابهجا میشود. موقعیت نسبی buf در داخل بافر داخلی تغییرنکرده باقی میماند.
در صورت بروز خطا، یک استثنا تنظیم کرده و
NULLرا برگردانید.buf نباید
NULLباشد.کد شبه تابع (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;
نمونهای برای ساخت رشتهی b'abc'¶
نمونهای برای ساخت رشتهی بایت b"abc"، با اندازهی ثابت ۳ بایت:
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);
}
بهروزرسانی کد PyBytes_FromStringAndSize()¶
نمونهای از کد که از API منسوخشدهی نرم PyBytes_FromStringAndSize(NULL, size) استفاده میکند:
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);
}
بهروزرسانی کد _PyBytes_Resize()¶
نمونهای از کد که از API منسوخشدهی نرم _PyBytes_Resize() استفاده میکند:
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;
}