پروتکل نگاشت¶

همچنین PyObject_GetItem()، PyObject_SetItem() و PyObject_DelItem() را ببینید.

int PyMapping_Check(PyObject *o)¶

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

اگر شیء پروتکل نگاشت را فراهم کند یا از اسلایس‌کردن پشتیبانی کند، 1 را برمی‌گرداند و در غیر این صورت 0. توجه داشته باشید که برای کلاس‌های پایتون دارای متد __getitem__() مقدار 1 را برمی‌گرداند، زیرا به‌طور کلی تشخیص اینکه کلاس از چه نوع کلیدهایی پشتیبانی می‌کند امکان‌پذیر نیست. این تابع همیشه با موفقیت انجام می‌شود.

Py_ssize_t PyMapping_Size(PyObject *o)¶

Py_ssize_t PyMapping_Length(PyObject *o)¶

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

در صورت موفقیت، تعداد کلیدهای شیء o را برمی‌گرداند و در صورت شکست -1. این معادل عبارت پایتونی len(o) است.

PyObject *PyMapping_GetItemString(PyObject *o, const char *key)¶

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

این همان PyObject_GetItem() است، اما کلید به‌جای PyObject*، به‌صورت یک رشته‌ی بایتِ کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود.

int PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)¶

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

گونه‌ای از PyObject_GetItem() که اگر کلید پیدا نشود، استثنای KeyError را ایجاد نمی‌کند.

اگر کلید یافت شود، 1 را برمی‌گرداند و *result را روی یک ارجاع قوی جدید به مقدار متناظر تنظیم می‌کند. اگر کلید یافت نشود، 0 را برمی‌گرداند و *result را روی NULL تنظیم می‌کند؛ استثنای KeyError سرکوب می‌شود. اگر خطایی غیر از KeyError رخ دهد، -1 را برمی‌گرداند و *result را روی NULL تنظیم می‌کند.

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

int PyMapping_GetOptionalItemString(PyObject *obj, const char *key, PyObject **result)¶

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

این همان PyMapping_GetOptionalItem() است، اما key به‌صورت یک رشته بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه یک PyObject*.

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

int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)¶

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

این همان PyObject_SetItem() است، اما key به‌جای PyObject* به‌صورت یک رشته‌ی بایتِ کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود.

int PyMapping_DelItem(PyObject *o, PyObject *key)¶

این یک نام مستعار برای PyObject_DelItem() است.

int PyMapping_DelItemString(PyObject *o, const char *key)¶

این همان PyObject_DelItem() است، اما key به‌صورت یک رشته‌ی بایت‌های کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه به‌صورت PyObject*.

int PyMapping_HasKeyWithError(PyObject *o, PyObject *key)¶

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

اگر شیء نگاشت کلید key را داشته باشد 1 و در غیر این صورت 0 برمی‌گرداند. این معادل عبارت پایتونی key in o است. در صورت شکست، -1 برمی‌گرداند.

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

int PyMapping_HasKeyStringWithError(PyObject *o, const char *key)¶

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

این همان PyMapping_HasKeyWithError() است، اما key به‌عنوان یک رشته‌ی بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه به‌صورت PyObject*.

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

int PyMapping_HasKey(PyObject *o, PyObject *key)¶

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

اگر شیء نگاشت دارای کلید کلید باشد، 1 و در غیر این صورت 0 برمی‌گرداند. این معادل عبارت پایتونی key in o است. این تابع همیشه با موفقیت اجرا می‌شود.

نکته

استثناهایی که هنگام فراخوانی متد __getitem__() توسط این تابع رخ می‌دهند، بی‌صدا نادیده گرفته می‌شوند. برای مدیریت صحیح خطاها، به جای آن از PyMapping_HasKeyWithError()، PyMapping_GetOptionalItem() یا PyObject_GetItem() استفاده کنید.

int PyMapping_HasKeyString(PyObject *o, const char *key)¶

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

این همان PyMapping_HasKey() است، با این تفاوت که key به‌عنوان یک رشته‌ی بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه یک PyObject*.

نکته

استثناهایی که هنگام فراخوانی متد __getitem__() یا هنگام ایجاد شیء موقت str رخ می‌دهند، بی‌صدا نادیده گرفته می‌شوند. برای مدیریت صحیح خطا، به جای آن از PyMapping_HasKeyStringWithError()، PyMapping_GetOptionalItemString() یا PyMapping_GetItemString() استفاده کنید.

PyObject *PyMapping_Keys(PyObject *o)¶

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

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

تغییر یافته در نسخه‌ی 3.7: پیش‌تر، این تابع یک فهرست یا یک تاپل را برمی‌گرداند.

PyObject *PyMapping_Values(PyObject *o)¶

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

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

تغییر یافته در نسخه‌ی 3.7: پیش‌تر، این تابع یک فهرست یا یک تاپل را برمی‌گرداند.

PyObject *PyMapping_Items(PyObject *o)¶

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

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

تغییر یافته در نسخه‌ی 3.7: پیش‌تر، این تابع یک فهرست یا یک تاپل را برمی‌گرداند.