رشته‌ها و بافرها¶

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

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

سه روش برای تبدیل رشته‌ها و بافرها به C وجود دارد:

• قالب‌هایی مانند y* و s* یک ساختار Py_buffer را پر می‌کنند. این کار بافر زیرین را قفل می‌کند تا فراخواننده بتواند متعاقباً حتی درون یک بلوک Py_BEGIN_ALLOW_THREADS از بافر استفاده کند، بدون خطر تغییر اندازه یا نابود شدن داده‌های تغییرپذیر. در نتیجه، پس از اتمام پردازش داده‌ها (یا در هر حالت خاتمه زودهنگام)، باید PyBuffer_Release() را فراخوانی کنید.

• قالب‌های es، es#، et و et# بافر نتیجه را تخصیص می‌دهند. باید پس از پایان پردازش داده‌ها (یا در هر مورد خاتمه زودهنگام)، PyMem_Free() را فراخوانی کنید.

• قالب‌های دیگر یک str یا یک شیء شبه‌بایت فقط‌خواندنی، مانند bytes، می‌گیرند و اشاره‌گری از نوع const char * به بافر آن فراهم می‌کنند. در این حالت بافر «امانتی» است: توسط شیء پایتون متناظر مدیریت می‌شود و عمر آن با عمر این شیء مشترک است. شما نیازی نخواهید داشت که خودتان هیچ حافظه‌ای را آزاد کنید.

  برای اطمینان از این‌که بافر زیرین بتواند به‌طور ایمن به امانت گرفته شود، فیلد PyBufferProcs.bf_releasebuffer مربوط به شیء باید NULL باشد. این امر نه‌تنها اشیاء تغییرپذیر رایج مانند bytearray، بلکه برخی اشیاء فقط‌خواندنی مانند memoryview از bytes را نیز منع می‌کند.

  علاوه بر این الزام bf_releasebuffer، هیچ بررسی‌ای برای تأیید اینکه شیء ورودی تغییرناپذیر است یا خیر انجام نمی‌شود (مثلاً اینکه آیا شیء به درخواست بافر نوشتنی ترتیب اثر می‌دهد، یا اینکه آیا نخ دیگری می‌تواند داده‌ها را تغییر دهد).

s (str) [const char *]

یک شیء یونیکد را به اشاره‌گر C به یک رشته نویسه‌ای تبدیل می‌کند. اشاره‌گر به یک رشته موجود، در متغیر اشاره‌گر نویسه که نشانی آن را ارسال می‌کنید، ذخیره می‌شود. رشته C با NUL پایان می‌یابد. رشته پایتون نباید شامل نقطه‌کدهای تهی تعبیه‌شده باشد؛ در صورت وجود، استثنای ValueError ایجاد می‌شود. اشیاء یونیکد با استفاده از کدگذاری 'utf-8' به رشته‌های C تبدیل می‌شوند. اگر این تبدیل شکست بخورد، استثنای UnicodeError ایجاد می‌شود.

نکته

این قالب اشیاء شبه‌بایت را نمی‌پذیرد. اگر می‌خواهید مسیرهای سامانه فایل‌بندی را بپذیرید و آن‌ها را به رشته‌های نویسه‌ای C تبدیل کنید، بهتر است از قالب O& با PyUnicode_FSConverter() به‌عنوان converter استفاده کنید.

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

s* (str یا bytes-like object) [Py_buffer]

این قالب اشیاء یونیکد و همچنین اشیاء شبه‌بایت را می‌پذیرد. این قالب ساختار Py_buffer فراهم‌شده توسط فراخواننده را پر می‌کند. در این حالت، رشته C حاصل ممکن است شامل بایت‌های تهی تعبیه‌شده باشد. اشیاء یونیکد با استفاده از کدگذاری 'utf-8' به رشته‌های C تبدیل می‌شوند.

s# (str، شیء شبه‌بایت فقط‌خواندنی) [const char *, Py_ssize_t]

مانند s*، با این تفاوت که یک بافر امانی فراهم می‌کند. نتیجه در دو متغیر C ذخیره می‌شود؛ اولی اشاره‌گری به یک رشته C و دومی طول آن است. رشته ممکن است حاوی بایت‌های تهی تعبیه‌شده باشد. اشیاء یونیکد با استفاده از کدگذاری 'utf-8' به رشته‌های C تبدیل می‌شوند.

z (str یا None) [const char *]

مانند s، اما شیء پایتون می‌تواند None نیز باشد، که در این صورت اشاره‌گر C برابر NULL قرار می‌گیرد.

z* (str، شیء شبه‌بایت یا None) [Py_buffer]

مانند s*، اما شیء پایتون می‌تواند None نیز باشد، که در این صورت عضو buf از ساختار Py_buffer برابر NULL قرار می‌گیرد.

z# (str، شیء شبه‌بایت فقط‌خواندنی یا None) [const char *, Py_ssize_t]

مانند s#، اما شیء پایتون می‌تواند None نیز باشد، که در این حالت اشاره‌گر C برابر NULL قرار می‌گیرد.

y (شیء شبه‌بایت فقط‌خواندنی) [const char *]

این قالب یک شیء شبه‌بایت را به اشاره‌گر C به یک رشته نویسه‌ی امانی تبدیل می‌کند؛ اشیاء یونیکد را نمی‌پذیرد. بافر بایت‌ها نباید حاوی بایت‌های تهی تعبیه‌شده باشد؛ در صورت وجود، استثنای ValueError ایجاد می‌شود.

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

y* (شیء شبه‌بایت) [Py_buffer]

این گونه از s* اشیای یونیکد را نمی‌پذیرد، فقط اشیای شبه‌بایت را می‌پذیرد. این روش توصیه‌شده برای پذیرش داده‌های دودویی است.

y# (شیء شبه‌بایت فقط‌خواندنی) [const char *, Py_ssize_t]

این گونه از s# اشیاء یونیکد را نمی‌پذیرد، بلکه فقط اشیاء شبه‌بایت را می‌پذیرد.

S (bytes) [PyBytesObject *]

نیازمند است که شیء پایتون یک شیء bytes باشد، بدون تلاش برای انجام هیچ تبدیلی. اگر شیء، یک شیء bytes نباشد، استثنای TypeError ایجاد می‌شود. متغیر C همچنین می‌تواند به صورت PyObject* اعلان شود.

Y (bytearray) [PyByteArrayObject *]

الزام می‌کند که شیء پایتون یک شیء bytearray باشد، بدون تلاش برای انجام هیچ تبدیلی. اگر شیء یک شیء bytearray نباشد، استثنای TypeError را ایجاد می‌کند. متغیر C همچنین می‌تواند به صورت PyObject* اعلان شود.

U (str) [PyObject *]

الزام می‌کند که شیء پایتون یک شیء یونیکد باشد، بدون تلاش برای انجام هیچ تبدیلی. اگر شیء یک شیء یونیکد نباشد، استثنای TypeError ایجاد می‌شود. متغیر C همچنین می‌تواند به‌صورت PyObject* اعلان شود.

w* (شیء شبه‌بایت خواندن-نوشتن) [Py_buffer]

این قالب هر شیء‌ای را که رابط بافر خواندن-نوشتن را پیاده‌سازی کند، می‌پذیرد. این قالب ساختار Py_buffer را که توسط فراخواننده فراهم شده است، پر می‌کند. بافر ممکن است شامل بایت‌های تهی تعبیه‌شده باشد. فراخواننده باید پس از پایان کار با بافر، PyBuffer_Release() را فراخوانی کند.

es (str) [const char *encoding, char **buffer]

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

این قالب به دو آرگومان نیاز دارد. آرگومان اول فقط به عنوان ورودی استفاده می‌شود و باید یک const char* باشد که به نام یک کدگذاری به صورت رشته‌ی پایان‌یافته با تهی (NUL-terminated) اشاره کند، یا NULL باشد که در این صورت کدگذاری 'utf-8' استفاده می‌شود. اگر کدگذاری نام‌برده برای پایتون شناخته‌شده نباشد، استثنایی مطرح می‌شود. آرگومان دوم باید یک char** باشد؛ مقدار اشاره‌گری که این آرگومان به آن ارجاع می‌دهد، به بافری حاوی محتوای متن آرگومان تنظیم خواهد شد. متن در کدگذاری تعیین‌شده توسط آرگومان اول کدگذاری خواهد شد.

PyArg_ParseTuple() یک بافر با اندازه‌ی مورد نیاز تخصیص می‌دهد، داده‌های کدگذاری‌شده را در این بافر کپی می‌کند و *buffer را طوری تنظیم می‌کند که به حافظه‌ی تازه تخصیص‌یافته ارجاع دهد. فراخوان‌کننده مسئول فراخوانی PyMem_Free() برای آزاد کردن بافر تخصیص‌یافته پس از استفاده است.

et (str، bytes یا bytearray) [const char *encoding, char **buffer]

مانند es است، با این تفاوت که اشیاء رشته بایتی بدون بازکدگذاری عبور داده می‌شوند. در عوض، پیاده‌سازی فرض می‌کند که شیء رشته بایتی از کدگذاری‌ای استفاده می‌کند که به‌عنوان پارامتر به آن داده شده است.

es# (str) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

این واریانتِ s# برای کدگذاری یونیکد به یک بافر نویسه‌ای به کار می‌رود. برخلاف قالب es، این واریانت اجازه‌ی داده‌های ورودی حاوی نویسه‌های تهی را می‌دهد.

این مورد به سه آرگومان نیاز دارد. آرگومان اول فقط به عنوان ورودی استفاده می‌شود و باید یک const char* باشد که به نام یک کدگذاری به صورت رشته خاتمه‌یافته با تهی (NUL) اشاره کند، یا NULL باشد که در این صورت از کدگذاری 'utf-8' استفاده می‌شود. اگر کدگذاری نام‌برده برای پایتون شناخته نشده باشد، استثنایی مطرح می‌شود. آرگومان دوم باید یک char** باشد؛ مقدار اشاره‌گری که به آن ارجاع داده می‌شود، به بافری شامل محتوای متن آرگومان تنظیم خواهد شد. متن در کدگذاری مشخص‌شده توسط آرگومان اول کدگذاری خواهد شد. آرگومان سوم باید اشاره‌گری به یک عدد صحیح باشد؛ عدد صحیح ارجاع‌شده به تعداد بایت‌های بافر خروجی تنظیم خواهد شد.

دو حالت کارکرد وجود دارد:

اگر *buffer یک اشاره‌گر NULL باشد، تابع بافری با اندازه‌ی مورد نیاز تخصیص می‌دهد، داده‌های کدگذاری‌شده را در این بافر کپی می‌کند و *buffer را برای ارجاع به فضای ذخیره‌سازی تازه تخصیص‌یافته تنظیم می‌کند. فراخواننده مسئول فراخوانی PyMem_Free() برای آزاد کردن بافر تخصیص‌یافته پس از استفاده است.

اگر *buffer به اشاره‌گری غیر NULL اشاره کند (بافری که از قبل تخصیص داده شده است)، PyArg_ParseTuple() از این مکان به عنوان بافر استفاده می‌کند و مقدار اولیه‌ی *buffer_length را به عنوان اندازه‌ی بافر تفسیر می‌کند. سپس داده‌های کدگذاری‌شده را در بافر کپی می‌کند و آن را با NUL پایان می‌دهد. اگر بافر به اندازه‌ی کافی بزرگ نباشد، یک ValueError تنظیم می‌شود.

در هر دو حالت، *buffer_length به طول داده‌های کدگذاری‌شده بدون بایت تهی انتهایی تنظیم می‌شود.

et# (str، bytes یا bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

مانند es# است، با این تفاوت که اشیاء رشته بایتی بدون بازکدگذاری، مستقیماً عبور داده می‌شوند. در عوض، پیاده‌سازی فرض می‌کند که شیء رشته بایتی از کدگذاری‌ای استفاده می‌کند که به‌عنوان پارامتر پاس داده شده است.

اعداد¶

این قالب‌ها اجازه می‌دهند اعداد پایتون یا نویسه‌های تکی به‌صورت اعداد C نمایش داده شوند. قالب‌هایی که به int، float یا complex نیاز دارند، می‌توانند برای تبدیل شیء پایتون به نوع موردنیاز از متدهای ویژه‌ی متناظر __index__()، __float__() یا __complex__() نیز استفاده کنند.

برای قالب‌های عدد صحیح علامت‌دار، اگر مقدار خارج از بازه‌ی مجاز برای نوع C باشد، OverflowError بالا آورده می‌شود. برای قالب‌های عدد صحیح بدون علامت، زمانی که فیلد دریافت‌کننده برای دریافت مقدار خیلی کوچک باشد، بیت‌های با ارزش‌تر به طور بی‌صدا قطع می‌شوند و زمانی که مقدار از حداکثر مقدار برای نوع C بزرگ‌تر یا از حداقل مقدار برای نوع عدد صحیح علامت‌دار متناظر با همان اندازه کوچک‌تر باشد، DeprecationWarning صادر می‌شود.

b (int) [unsigned char]

یک عدد صحیح نامنفی پایتون را به یک عدد صحیح بسیار کوچک بدون علامت تبدیل می‌کند که در یک unsigned char در زبان C ذخیره می‌شود.

B (int) [unsigned char]

یک عدد صحیح پایتون را بدون بررسی سرریز، به یک عدد صحیح بسیار کوچک ذخیره‌شده در یک unsigned char زبان C تبدیل کنید. یک عدد صحیح پایتون را به یک unsigned char زبان C تبدیل کنید.

h (int) [short int]

یک عدد صحیح پایتون را به short int در زبان C تبدیل می‌کند.

H (int) [unsigned short int]

یک عدد صحیح پایتون را به یک unsigned short int زبان C تبدیل کنید.

i (int) [int]

یک عدد صحیح پایتون را به یک int ساده‌ی C تبدیل می‌کند.

I (int) [unsigned int]

یک عدد صحیح پایتون را به یک unsigned int زبان C تبدیل کنید.

l (int) [long int]

یک عدد صحیح پایتون را به یک long int در C تبدیل می‌کند.

k (int) [unsigned long]

یک عدد صحیح پایتون را به یک unsigned long زبان C تبدیل کنید.

تغییر یافته در نسخه‌ی 3.14: در صورت وجود، از __index__() استفاده کنید.

L (int) [long long]

تبدیل یک عدد صحیح پایتون به یک long long در C.

K (int) [unsigned long long]

یک عدد صحیح پایتون را به یک unsigned long long زبان C تبدیل کنید.

تغییر یافته در نسخه‌ی 3.14: در صورت وجود، از __index__() استفاده کنید.

n (int) [Py_ssize_t]

یک عدد صحیح پایتون را به یک Py_ssize_t در C تبدیل می‌کند.

c (bytes یا bytearray با طول ۱) [char]

یک بایت پایتون را که به صورت شیء bytes یا bytearray به طول ۱ نمایش داده می‌شود، به یک char در C تبدیل می‌کند.

تغییر یافته در نسخه‌ی 3.3: اجازه‌ی استفاده از اشیاء bytearray.

C (str به طول ۱) [int]

یک نویسه‌ی پایتون را، که به‌صورت شیء str با طول ۱ نمایش داده می‌شود، به یک int در C تبدیل می‌کند.

f (float) [float]

تبدیل یک عدد ممیز شناور پایتون به یک float در C.

d (float) [double]

یک عدد ممیز شناور پایتون را به یک double در C تبدیل می‌کند.

D (complex) [Py_complex]

یک عدد مختلط پایتون را به ساختار Py_complex زبان C تبدیل می‌کند.

سایر اشیاء¶

O (شیء) [PyObject *]

یک شیء پایتون را (بدون هیچ تبدیلی) در یک اشاره‌گر شیء C ذخیره می‌کند. بدین ترتیب برنامه‌ی C همان شیء واقعی‌ای را که پاس داده‌شده است دریافت می‌کند. ارجاع قوی جدیدی به این شیء ایجاد نمی‌شود (یعنی شمارش ارجاع آن افزایش نمی‌یابد). اشاره‌گر ذخیره‌شده NULL نیست.

O! (شیء) [typeobject, PyObject *]

یک شیء پایتون را در یک اشاره‌گر شیء C ذخیره می‌کند. این مورد شبیه O است، اما دو آرگومان C می‌گیرد: آرگومان اول نشانی یک شیء نوع پایتون است و آرگومان دوم نشانی متغیر C (از نوع PyObject*) است که اشاره‌گر شیء در آن ذخیره می‌شود. اگر شیء پایتون نوع مورد نیاز را نداشته باشد، استثنای TypeError مطرح می‌شود.

O& (شیء) [مبدل، آدرس]

یک شیء پایتون را از طریق تابع مبدل به یک متغیر C تبدیل کنید. این تبدیل دو آرگومان می‌گیرد: اولی یک تابع است و دومی آدرس یک متغیر C (از نوع دلخواه) است که به void* تبدیل می‌شود. تابع مبدل به نوبه خود به شکل زیر فراخوانی می‌شود:

status = converter(object, address);

که در آن object شیء پایتونی است که باید تبدیل شود و address آرگومان void* است که به تابع PyArg_Parse* ارسال شده است. status بازگردانده‌شده باید در صورت تبدیل موفق 1 و در صورت شکست تبدیل 0 باشد. هنگامی که تبدیل شکست می‌خورد، تابع converter باید استثنایی را برانگیزد و محتوای address را بدون تغییر بگذارد.

اگر مبدل مقدار Py_CLEANUP_SUPPORTED را برگرداند، ممکن است در صورتی که تجزیه‌ی آرگومان‌ها در نهایت شکست بخورد، بار دوم فراخوانی شود، که این به مبدل فرصت می‌دهد تا هر حافظه‌ای را که پیش‌تر تخصیص داده بود آزاد کند. در این فراخوانی دوم، پارامتر object برابر NULL خواهد بود؛ address همان مقداری را خواهد داشت که در فراخوانی اصلی داشت.

نمونه‌هایی از مبدل‌ها: PyUnicode_FSConverter() و PyUnicode_FSDecoder().

تغییر یافته در نسخه‌ی 3.1: Py_CLEANUP_SUPPORTED افزوده شد.

p (bool) [int]

مقدار پاس‌داده‌شده را برای درستی آزمایش می‌کند (یک محمول بولی (predicate)) و نتیجه را به مقدار عدد صحیح true/false معادل آن در C تبدیل می‌کند. اگر عبارت درست باشد، int را روی 1 و اگر نادرست باشد، روی 0 قرار می‌دهد. این، هر مقدار معتبر پایتون را می‌پذیرد. برای اطلاعات بیشتر درباره‌ی اینکه پایتون چگونه مقادیر را برای درستی آزمایش می‌کند، آزمودن ارزش درستی را ببینید.

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

(items) (دنباله) [آیتم‌های منطبق]

شیء باید یک دنباله پایتونی باشد (به جز str، bytes یا bytearray) که طول آن برابر با تعداد واحدهای قالب (format unit) در items است. آرگومان‌های C باید با تک‌تک واحدهای قالب در items متناظر باشند. واحدهای قالب برای دنباله‌ها می‌توانند تودرتو باشند.

اگر items شامل واحدهای قالب (format unit) باشد که یک بافر امانتی (s، s#، z، z#، y یا y#) یا یک ارجاع امانتی (S، Y، U، O یا O!) را ذخیره می‌کنند، شیء باید یک تاپل پایتون باشد. مبدل واحد قالب O& در items نباید بافر امانتی یا ارجاع امانتی ذخیره کند.

تغییر یافته در نسخه‌ی 3.14: اشیاء str و bytearray دیگر به‌عنوان دنباله پذیرفته نمی‌شوند.

منسوخ شده از نسخه‌ی 3.14: اگر items شامل واحدهای قالب باشد که بافر امانتی یا ارجاع امانتی ذخیره می‌کنند، دنباله‌های غیرتاپلی منسوخ شده‌اند.

چند نویسه‌ی دیگر نیز در رشته‌ی قالب‌بندی معنا دارند. این نویسه‌ها نمی‌توانند درون پرانتزهای تودرتو به کار روند. آن‌ها عبارت‌اند از:

|

مشخص می‌کند که آرگومان‌های باقی‌مانده در فهرست آرگومان‌های پایتون اختیاری هستند. متغیرهای C متناظر با آرگومان‌های اختیاری باید به مقدار پیش‌فرض خود مقداردهی اولیه شوند --- وقتی یک آرگومان اختیاری مشخص نشده باشد، PyArg_ParseTuple() محتوای متغیر(های) C متناظر را دست‌نخورده می‌گذارد. برای مثال، رشته‌ی قالب "OO|OO" با امضای پایتون f(a, b, c=None, d=None) متناظر است.

$

فقط PyArg_ParseTupleAndKeywords(): مشخص می‌کند که آرگومان‌های باقی‌مانده در فهرست آرگومان‌های پایتون فقط‌کلیدواژه هستند. اگر | قبل از $ مشخص شده باشد، آن‌ها اختیاری هستند، و در غیر این صورت ضروری. | نمی‌تواند بعد از $ مشخص شود. برای مثال، رشته‌ی قالب "O|O$O" با امضای پایتون f(a, b=None, *, c=None) متناظر است، و رشته‌ی قالب "OO$OO" با f(a, b, *, c, d) متناظر است.

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

:

فهرست واحدهای قالب در اینجا به پایان می‌رسد؛ رشته‌ای که پس از دونقطه می‌آید به‌عنوان نام تابع در پیام‌های خطا استفاده می‌شود («مقدار مرتبط» استثنایی که PyArg_ParseTuple() ایجاد می‌کند).

;

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

توجه داشته باشید که هر ارجاع به شیء پایتون که به فراخوان‌کننده ارائه می‌شود، ارجاعی امانتی است؛ آن‌ها را آزاد نکنید (یعنی شمارش ارجاع آن‌ها را کاهش ندهید)!

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

برای آنکه تبدیل با موفقیت انجام شود، شیء arg باید با قالب مطابقت داشته باشد و قالب باید به‌طور کامل مصرف شود. در صورت موفقیت، توابع PyArg_Parse* مقدار true را برمی‌گردانند، در غیر این صورت مقدار false را برمی‌گردانند و یک استثنای مناسب ایجاد می‌کنند. هنگامی که توابع PyArg_Parse* به دلیل شکست تبدیل در یکی از واحدهای قالب با شکست مواجه می‌شوند، متغیرهایی که در آدرس‌های متناظر با آن واحد قالب و واحدهای قالب بعدی قرار دارند، دست‌نخورده باقی می‌مانند.

توابع API¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶

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

پارامترهای تابعی را که فقط پارامترهای جایگاهی می‌پذیرد، به متغیرهای محلی تجزیه می‌کند. در صورت موفقیت true برمی‌گرداند؛ در صورت شکست، false برمی‌گرداند و استثنای مناسب را برمی‌انگیزد.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶

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

یکسان با PyArg_ParseTuple() است، با این تفاوت که به‌جای تعداد متغیری از آرگومان‌ها، یک va_list را می‌پذیرد.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶

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

پارامترهای تابعی را که هم پارامترهای جایگاهی و هم پارامترهای کلیدواژه‌ای می‌پذیرد، به متغیرهای محلی تجزیه می‌کند. آرگومان keywords آرایه‌ای خاتمه‌یافته با NULL از نام‌های پارامترهای کلیدواژه‌ای است که به‌صورت رشته‌های C خاتمه‌یافته با تهی و کدگذاری‌شده با اسکی یا UTF-8 مشخص شده‌اند. نام‌های خالی نشان‌دهنده‌ی پارامترهای فقط‌جایگاهی هستند. در صورت موفقیت، true برمی‌گرداند؛ در صورت شکست، false برمی‌گرداند و استثنای مناسب را ایجاد می‌کند.

نکته

اعلان پارامتر keywords در C به صورت char *const* و در C++ به صورت const char *const* است. این را می‌توان با ماکروی PY_CXX_CONST بازنویسی کرد.

تغییر یافته در نسخه‌ی 3.6: پشتیبانی از پارامترهای فقط‌جایگاهی افزوده شد.

تغییر یافته در نسخه‌ی 3.13: پارامتر keywords اکنون در C از نوع char *const* و در C++ از نوع const char *const* است، به‌جای char**. پشتیبانی از نام‌های غیراسکی برای پارامترهای کلیدواژه‌ای افزوده شد.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶

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

یکسان با PyArg_ParseTupleAndKeywords() است، با این تفاوت که به جای تعداد متغیری از آرگومان‌ها، یک va_list می‌پذیرد.

int PyArg_ValidateKeywordArguments(PyObject*)¶

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

مطمئن شوید که کلیدهای دیکشنری آرگومان keywords رشته باشند. این کار تنها در صورتی لازم است که از PyArg_ParseTupleAndKeywords() استفاده نشده باشد، زیرا خودِ آن از پیش این بررسی را انجام می‌دهد.

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

int PyArg_Parse(PyObject *args, const char *format, ...)¶

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

پارامتر تابعی را که یک پارامتر جایگاهی منفرد می‌گیرد، در یک متغیر محلی پارس می‌کند. در صورت موفقیت true را برمی‌گرداند؛ در صورت شکست، false برمی‌گرداند و استثنای مناسب را ایجاد می‌کند.

مثال:

// Function using METH_O calling convention
static PyObject*
my_function(PyObject *module, PyObject *arg)
{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        return NULL;
    }
    // ... use value ...
}

int PyArg_ParseArray(PyObject *const *args, Py_ssize_t nargs, const char *format, ...)¶

پارامترهای تابعی که تنها پارامترهای آرایه‌ای می‌پذیرد را به متغیرهای محلی تجزیه کنید (یعنی تابعی که از قرارداد فراخوانی METH_FASTCALL استفاده می‌کند). در صورت موفقیت، مقدار true را برمی‌گرداند؛ در صورت شکست، false را برگردانده و استثنای مناسب را بالا می‌آورد.

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

int PyArg_ParseArrayAndKeywords(PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames, const char *format, const char *const *kwlist, ...)¶

پارامترهای تابعی که هم پارامترهای آرایه‌ای و هم کلیدواژه‌ای می‌پذیرد را به متغیرهای محلی تجزیه کنید (یعنی تابعی که از قرارداد فراخوانی METH_FASTCALL | METH_KEYWORDS استفاده می‌کند). در صورت موفقیت، مقدار true را برمی‌گرداند؛ در صورت شکست، false را برگردانده و استثنای مناسب را بالا می‌آورد.

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

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)¶

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

شکل ساده‌تری از بازیابی پارامتر که برای تعیین نوع آرگومان‌ها از رشته قالب استفاده نمی‌کند. توابعی که از این روش برای بازیابی پارامترهای خود استفاده می‌کنند باید در جدول‌های تابع یا متد به‌صورت METH_VARARGS اعلان شوند. تاپل حاوی پارامترهای واقعی باید به‌عنوان args ارسال شود؛ واقعاً باید یک تاپل باشد. طول تاپل باید حداقل min و حداکثر max باشد؛ min و max می‌توانند برابر باشند. آرگومان‌های اضافی باید به تابع ارسال شوند که هر یک باید اشاره‌گری به متغیر PyObject* باشد؛ این‌ها با مقادیر args پر خواهند شد؛ آن‌ها حاوی ارجاع‌های امانتی خواهند بود. متغیرهای متناظر با پارامترهای اختیاری که توسط args داده نشده‌اند، پر نخواهند شد؛ این متغیرها باید توسط فراخواننده مقداردهی اولیه شوند. این تابع در صورت موفقیت true برمی‌گرداند و اگر args یک تاپل نباشد یا تعداد عناصر نادرستی داشته باشد false برمی‌گرداند؛ در صورت شکست، یک استثنا تنظیم خواهد شد.

این مثالی از استفاده از این تابع است که از کدهای منبع ماژول کمکی _weakref برای ارجاع‌های ضعیف برگرفته شده است:

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}

فراخوانی PyArg_UnpackTuple() در این مثال کاملاً معادل این فراخوانی PyArg_ParseTuple() است:

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

PY_CXX_CONST¶

مقداری که در صورت وجود، پیش از char *const* در اعلان پارامتر keywords در PyArg_ParseTupleAndKeywords() و PyArg_VaParseTupleAndKeywords() درج می‌شود. مقدار پیش‌فرض برای C خالی و برای C++ مقدار const است (const char *const*). برای تغییر این مقدار، آن را پیش از گنجاندن Python.h به مقدار دلخواه تعریف کنید.

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