اشیای دیکشنری¶

type PyDictObject¶

این زیرنوع «subtype» از PyObject نمایانگر یک شیء دیکشنری پایتون است.

PyTypeObject PyDict_Type¶

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

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

int PyDict_Check(PyObject *p)¶

Thread safety: Atomic.

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

int PyDict_CheckExact(PyObject *p)¶

Thread safety: Atomic.

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

PyObject *PyDict_New()¶

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

یک دیکشنری خالی جدید برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyDictProxy_New(PyObject *mapping)¶

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

یک شیء types.MappingProxyType برای نگاشتی که رفتار فقط‌خواندنی را اعمال می‌کند بازمی‌گرداند. این معمولاً برای ایجاد نمایی استفاده می‌شود که از تغییر دیکشنری در نوع‌های کلاس غیرپویا جلوگیری کند.

اولین آرگومان می‌تواند یک dict، یک frozendict یا یک نگاشت باشد.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

PyTypeObject PyDictProxy_Type¶

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

شیء نوع برای اشیاء پراکسی نگاشت ایجاد‌شده توسط PyDictProxy_New() و برای ویژگی __dict__ فقط‌خواندنی بسیاری از نوع‌های توکار. یک نمونه‌ی PyDictProxy_Type نمای پویا و فقط‌خواندنی از یک دیکشنری زیرین ارائه می‌دهد: تغییرات دیکشنری زیرین در پراکسی منعکس می‌شوند، اما خود پراکسی از عملیات تغییر پشتیبانی نمی‌کند. این معادل types.MappingProxyType در پایتون است.

void PyDict_Clear(PyObject *p)¶

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

یک دیکشنری موجود را از تمام جفت‌های کلید-مقدار خالی می‌کند.

اگر آرگومان یک dict یا زیرکلاس dict نباشد، هیچ کاری انجام ندهید.

int PyDict_Contains(PyObject *p, PyObject *key)¶

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

تعیین می‌کند که آیا دیکشنری p شامل key است یا خیر. اگر آیتمی در p با key مطابقت داشته باشد، 1 را برمی‌گرداند، در غیر این صورت 0 را برمی‌گرداند. در صورت خطا، -1 را برمی‌گرداند. این معادل عبارت پایتونی key in p است.

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

نکته

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

int PyDict_ContainsString(PyObject *p, const char *key)¶

Thread safety: Atomic.

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

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

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

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

PyObject *PyDict_Copy(PyObject *p)¶

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

یک دیکشنری جدید برمی‌گرداند که شامل همان جفت‌های کلید-مقدار p است.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶

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

val را با کلید key در دیکشنری p درج می‌کند. key باید هش‌پذیر باشد؛ در غیر این صورت، استثنای TypeError ایجاد خواهد شد. در صورت موفقیت 0 یا در صورت شکست -1 برمی‌گرداند. این تابع ارجاعی به val را «دزدی» نمی‌کند.

نکته

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶

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

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

int PyDict_DelItem(PyObject *p, PyObject *key)¶

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

ورودی دارای کلید key را از دیکشنری p حذف می‌کند. key باید hashable باشد؛ در غیر این صورت، TypeError مطرح می‌شود. اگر key در دیکشنری نباشد، KeyError مطرح می‌شود. در صورت موفقیت 0 و در صورت شکست -1 را برمی‌گرداند.

نکته

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

int PyDict_DelItemString(PyObject *p, const char *key)¶

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

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

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)¶

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

بازگرداندن یک ارجاع قوی جدید به شیء موجود در دیکشنری p که کلید key را دارد:

• اگر کلید موجود باشد، *result را برابر یک ارجاع قوی جدید به مقدار قرار می‌دهد و 1 را برمی‌گرداند.

• اگر کلید وجود نداشته باشد، *result برابر NULL قرار می‌گیرد و 0 بازگردانده می‌شود.

• در صورت خطا، یک استثنا برمی‌انگیزد، *result را برابر NULL قرار می‌دهد و -1 برمی‌گرداند.

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

نکته

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

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

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

همچنین تابع PyObject_GetItem() را ببینید.

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶

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

ارجاع امانتی به شیء دارای کلید key را از دیکشنری p برمی‌گرداند. اگر کلید key موجود نباشد، NULL را بدون تنظیم استثنا برمی‌گرداند.

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

نکته

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

نکته

در ساخت‌ نخ‌آزاد، اگر نخ دیگری دیکشنری را به‌طور هم‌زمان تغییر دهد، ارجاع امانتی برگردانده‌شده ممکن است نامعتبر شود. استفاده از PyDict_GetItemRef() را ترجیح دهید که یک ارجاع قوی برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.10: فراخوانی این API بدون وضعیت نخ متصل به دلایل تاریخی مجاز بود. این کار دیگر مجاز نیست.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)¶

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

گونه‌ای از PyDict_GetItem() که استثناها را فرونمی‌نشاند. اگر استثنایی رخ داده باشد، NULL را همراه با استثنای تنظیم‌شده برمی‌گرداند. اگر کلید موجود نباشد، NULL را بدون استثنای تنظیم‌شده برمی‌گرداند.

نکته

در ساخت‌ نخ‌آزاد، اگر نخ دیگری دیکشنری را به‌طور هم‌زمان تغییر دهد، ارجاع امانتی برگردانده‌شده ممکن است نامعتبر شود. استفاده از PyDict_GetItemRef() را ترجیح دهید که یک ارجاع قوی برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

PyObject *PyDict_GetItemString(PyObject *p, const char *key)¶

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

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

نکته

استثناهایی که هنگام فراخوانی متدهای __hash__() و __eq__() توسط این تابع یا هنگام ایجاد شیء موقت str رخ می‌دهند، به‌صورت خاموش نادیده گرفته می‌شوند. به‌جای آن، بهتر است از تابع PyDict_GetItemWithError() به‌همراه key PyUnicode_FromString() خودتان استفاده کنید.

نکته

در free-threaded build، اگر نخ دیگری دیکشنری را به‌صورت هم‌زمان تغییر دهد، ممکن است borrowed reference بازگردانده‌شده نامعتبر شود. ترجیحاً از PyDict_GetItemStringRef() استفاده کنید که یک strong reference برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)¶

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

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

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

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)¶

مقدار بازگشتی: مرجع امانتی. Thread safety: Safe to call from multiple threads with external synchronization only.

این همان dict.setdefault() در سطح پایتون است. در صورت وجود، مقدار متناظر با key را از دیکشنری p برمی‌گرداند. اگر کلید در دیکشنری نباشد، با مقدار defaultobj درج می‌شود و defaultobj برگردانده می‌شود. این تابع، تابع هش key را تنها یک بار ارزیابی می‌کند، به‌جای اینکه آن را به‌طور مستقل برای جستجو و درج ارزیابی کند.

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

نکته

در نسخه‌ی نخ‌آزاد، اگر نخ دیگری دیکشنری را هم‌زمان تغییر دهد، ممکن است ارجاع امانتی بازگردانده‌شده نا‌معتبر شود. ترجیح دهید از PyDict_SetDefaultRef() استفاده کنید که یک ارجاع قوی برمی‌گرداند.

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)¶

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

در صورتی که کلید از قبل در دیکشنری وجود نداشته باشد، default_value را با کلید key در دیکشنری p درج می‌کند. اگر result برابر NULL نباشد، *result به یک strong reference به default_value (در صورتی که کلید وجود نداشته باشد) یا به مقدار موجود (در صورتی که key از قبل در دیکشنری وجود داشته باشد) تنظیم می‌شود. اگر کلید وجود داشته باشد و default_value درج نشده باشد، 1 را برمی‌گرداند، و اگر کلید وجود نداشته باشد و default_value درج شده باشد، 0 را برمی‌گرداند. در صورت شکست، -1 را برمی‌گرداند، یک استثنا تنظیم می‌کند و *result را برابر NULL قرار می‌دهد.

برای شفافیت: اگر پیش از فراخوانی این تابع، ارجاع قوی به default_value داشته باشید، پس از بازگشت آن، ارجاع قوی به هر دو default_value و *result را در اختیار دارید (اگر NULL نباشد). این دو ممکن است به یک شیء واحد اشاره داشته باشند: در این صورت دو ارجاع جداگانه به آن در اختیار دارید.

نکته

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

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

int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)¶

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

کلید key را از دیکشنری p حذف می‌کند و به‌صورت اختیاری مقدار حذف‌شده را برمی‌گرداند. اگر کلید وجود نداشته باشد، استثنای KeyError صادر نمی‌شود.

• اگر کلید موجود باشد، *result را در صورتی که result برابر NULL نباشد، برابر ارجاعی جدید به مقدار حذف‌شده قرار می‌دهد و 1 را برمی‌گرداند.

• اگر کلید وجود نداشته باشد، *result را در صورتی که result برابر NULL نباشد برابر NULL قرار می‌دهد و 0 را برمی‌گرداند.

• در صورت بروز خطا، یک استثنا ایجاد کرده و -1 را برمی‌گرداند.

شبیه dict.pop() است، اما بدون مقدار پیش‌فرض و در صورت نبود کلید، استثنای KeyError ایجاد نمی‌کند.

نکته

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

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

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)¶

Thread safety: Atomic.

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

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

PyObject *PyDict_Items(PyObject *p)¶

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

یک PyListObject حاوی همه‌ی آیتم‌های دیکشنری را برمی‌گرداند.

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

PyObject *PyDict_Keys(PyObject *p)¶

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

یک PyListObject شامل همه‌ی کلیدهای دیکشنری برمی‌گرداند.

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

PyObject *PyDict_Values(PyObject *p)¶

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

یک PyListObject شامل تمام مقادیر دیکشنری p برمی‌گرداند.

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

Py_ssize_t PyDict_Size(PyObject *p)¶

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

تعداد آیتم‌های موجود در دیکشنری را برمی‌گرداند. این معادل len(p) روی یک دیکشنری است.

آرگومان می‌تواند یک dict یا یک frozendict باشد.

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

Py_ssize_t PyDict_GET_SIZE(PyObject *p)¶

Thread safety: Atomic.

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

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶

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

تمام جفت‌های کلید-مقدار در دیکشنری p را پیمایش می‌کند. مقدار Py_ssize_t که توسط ppos مشخص می‌شود، باید پیش از نخستین فراخوانی این تابع برای آغاز پیمایش، با 0 مقداردهی اولیه شود؛ این تابع برای هر جفت موجود در دیکشنری مقدار true و پس از گزارش همه‌ی جفت‌ها مقدار false را برمی‌گرداند. پارامترهای pkey و pvalue باید به متغیرهایی از نوع PyObject* اشاره کنند که به‌ترتیب با هر کلید و مقدار پر می‌شوند، یا می‌توانند NULL باشند. هر ارجاعی که از طریق آن‌ها بازگردانده می‌شود، امانتی است. ppos نباید در طول پیمایش تغییر داده شود. مقدار آن نشان‌دهنده‌ی آفست‌هایی در ساختار داخلی دیکشنری است و از آنجا که این ساختار خلوت است، این آفست‌ها متوالی نیستند.

اولین آرگومان می‌تواند یک dict یا یک frozendict باشد.

برای مثال:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

دیکشنری p نباید در حین پیمایش تغییر داده شود. تغییر دادن مقدارهای کلیدها هنگام پیمایش دیکشنری ایمن است، اما تنها تا زمانی که مجموعه‌ی کلیدها تغییر نکند. برای مثال:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) {
        return -1;
    }
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

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

Py_BEGIN_CRITICAL_SECTION(self->dict);
while (PyDict_Next(self->dict, &pos, &key, &value)) {
    ...
}
Py_END_CRITICAL_SECTION();

این تابع روی یک frozendict نخ‌ایمن است.

نکته

در نسخه‌ی نخ‌آزاد، می‌توان از این تابع به‌طور ایمن درون بخش بحرانی استفاده کرد. با این حال، ارجاع‌های برگردانده‌شده برای pkey و pvalue امانتی هستند و تنها تا زمانی که بخش بحرانی برقرار است معتبرند. اگر نیاز دارید از این اشیاء خارج از بخش بحرانی یا در زمانی که بخش بحرانی ممکن است معلق شود استفاده کنید، یک ارجاع قوی ایجاد کنید (برای مثال، با استفاده از Py_NewRef()).

تغییر یافته در نسخه‌ی 3.15: همچنین frozendict را بپذیرید.

int PyDict_Merge(PyObject *a, PyObject *b, int override)¶

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

بر روی شیء نگاشت b پیمایش می‌کند و جفت‌های کلید-مقدار را به دیکشنری a اضافه می‌کند. b می‌تواند یک دیکشنری یا هر شیء‌ای باشد که از PyMapping_Keys() و PyObject_GetItem() پشتیبانی کند. اگر override درست باشد، جفت‌های موجود در a در صورتی که کلید مطابقی در b یافت شود جایگزین می‌شوند، در غیر این صورت جفت‌ها تنها در صورتی اضافه می‌شوند که کلید مطابقی در a وجود نداشته باشد. در صورت موفقیت 0 و در صورت ایجاد استثنا -1 بازگردانده می‌شود.

نکته

در free-threaded build، وقتی b یک dict (با پیمایش‌گر استاندارد) باشد، هر دو a و b در طول عملیات قفل می‌شوند. وقتی b یک نگاشت غیردیکشنری باشد، فقط a قفل می‌شود؛ b ممکن است توسط نخ دیگری به‌طور هم‌زمان تغییر یابد.

int PyDict_Update(PyObject *a, PyObject *b)¶

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

این همان PyDict_Merge(a, b, 1) در C است و مشابه a.update(b) در پایتون است، با این تفاوت که PyDict_Update() در صورتی که آرگومان دوم ویژگی «keys» نداشته باشد، به پیمایش دنباله‌ای از جفت‌های کلید-مقدار بازنمی‌گردد. در صورت موفقیت 0 و در صورت بروز استثنا -1 را برمی‌گرداند.

نکته

در free-threaded build، وقتی b یک dict (با پیمایش‌گر استاندارد) باشد، هر دو a و b در طول عملیات قفل می‌شوند. وقتی b یک نگاشت غیردیکشنری باشد، فقط a قفل می‌شود؛ b ممکن است توسط نخ دیگری به‌طور هم‌زمان تغییر یابد.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)¶

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

به‌روزرسانی یا ادغام در دیکشنری a، از جفت‌های کلید-مقدار در seq2. seq2 باید یک شیء پیمایش‌پذیر باشد که اشیاء پیمایش‌پذیر با طول ۲ تولید می‌کند که به‌عنوان جفت‌های کلید-مقدار در نظر گرفته می‌شوند. در صورت وجود کلیدهای تکراری، اگر override درست باشد آخری برنده می‌شود، در غیر این صورت اولی برنده می‌شود. در صورت موفقیت 0 و در صورت پرتاب استثنا -1 برمی‌گرداند. معادل پایتونی (به‌جز مقدار بازگشتی):

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

نکته

در ساخت‌ نخ‌آزاد، فقط a قفل می‌شود. پیمایش روی seq2 همگام‌سازی نمی‌شود؛ ممکن است seq2 به‌طور هم‌زمان توسط نخ دیگری تغییر یابد.

int PyDict_AddWatcher(PyDict_WatchCallback callback)¶

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

callback را به‌عنوان دیده‌بان (watcher) دیکشنری ثبت می‌کند. یک شناسه‌ی عدد صحیح نامنفی برمی‌گرداند که باید به فراخوانی‌های آتی PyDict_Watch() پاس داده شود. در صورت خطا (برای مثال، وقتی دیگر شناسه‌ی دیده‌بانی در دسترس نباشد)، مقدار -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند.

نکته

این تابع به‌طور داخلی همگام‌سازی نمی‌شود. در نسخه‌ی نخ‌آزاد، فراخوان‌کنندگان باید اطمینان حاصل کنند که هیچ فراخوانی هم‌زمانی از PyDict_AddWatcher() یا PyDict_ClearWatcher() در حال انجام نیست.

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

int PyDict_ClearWatcher(int watcher_id)¶

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

پایشگر (watcher) شناسایی‌شده با watcher_id را که پیش‌تر از PyDict_AddWatcher() برگردانده شده است، پاک می‌کند. در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند (مثلاً اگر watcher_id داده‌شده هرگز ثبت نشده باشد.)

نکته

این تابع به‌طور داخلی همگام‌سازی نمی‌شود. در نسخه‌ی نخ‌آزاد، فراخوان‌کنندگان باید اطمینان حاصل کنند که هیچ فراخوانی هم‌زمانی از PyDict_AddWatcher() یا PyDict_ClearWatcher() در حال انجام نیست.

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

int PyDict_Watch(int watcher_id, PyObject *dict)¶

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

دیکشنری dict را به‌عنوان تحت نظر علامت‌گذاری می‌کند. کال‌بکی که PyDict_AddWatcher() شناسه‌ی watcher_id را به آن اعطا کرده است، هنگامی که dict تغییر داده شود یا تخصیص‌گشایی شود فراخوانی خواهد شد. در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند.

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

int PyDict_Unwatch(int watcher_id, PyObject *dict)¶

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

دیکشنری dict را به‌عنوان دیگر دیده‌بانی‌نشده علامت‌گذاری می‌کند. کال‌بکی که PyDict_AddWatcher() شناسه‌ی watcher_id را به آن اعطا کرده است، دیگر زمانی که dict تغییر داده یا آزادسازی شود، فراخوانی نخواهد شد. دیکشنری باید پیش‌تر توسط این دیده‌بان دیده‌بانی شده باشد. در صورت موفقیت 0 و در صورت خطا -1 را برمی‌گرداند.

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

type PyDict_WatchEvent¶

برشمردن رویدادهای ممکن دیده‌بان دیکشنری: PyDict_EVENT_ADDED، PyDict_EVENT_MODIFIED، PyDict_EVENT_DELETED، PyDict_EVENT_CLONED، PyDict_EVENT_CLEARED یا PyDict_EVENT_DEALLOCATED.

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

PY_FOREACH_DICT_EVENT(V)¶

ماکرو V را روی هر پسوند از ثابت‌های PyDict_WatchEvent اعمال کنید. در حال حاضر به صورت V(ADDED) V(MODIFIED) V(DELETED) V(CLONED) V(CLEARED) V(DEALLOCATED) گسترش می‌یابد. ماکرو V باید یک نام رویداد را بپذیرد و هرگونه علائم نگارشی مورد نیاز بین گسترش‌ها را فراهم کند.

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)¶

نوع تابع کال‌بک ناظر دیکشنری.

اگر event برابر PyDict_EVENT_CLEARED یا PyDict_EVENT_DEALLOCATED باشد، هر دو key و new_value برابر NULL خواهند بود. اگر event برابر PyDict_EVENT_ADDED یا PyDict_EVENT_MODIFIED باشد، new_value مقدار جدید برای key خواهد بود. اگر event برابر PyDict_EVENT_DELETED باشد، key در حال حذف شدن از دیکشنری است و new_value برابر NULL خواهد بود.

PyDict_EVENT_CLONED زمانی رخ می‌دهد که dict قبلاً خالی بوده و دیکشنری دیگری در آن ادغام شود. برای حفظ کارایی این عملیات، در این حالت رویدادهای PyDict_EVENT_ADDED به ازای هر کلید صادر نمی‌شوند؛ در عوض یک PyDict_EVENT_CLONED واحد صادر می‌شود و key دیکشنری منبع خواهد بود.

کال‌بک می‌تواند dict را بازرسی کند، اما نباید آن را تغییر دهد؛ انجام این کار می‌تواند اثرات غیرقابل پیش‌بینی، از جمله بازگشت بی‌نهایت، داشته باشد. در کال‌بک، اجرای کد پایتون را فعال نکنید، زیرا ممکن است به عنوان یک عارضه جانبی، دیکشنری را تغییر دهد.

اگر event برابر PyDict_EVENT_DEALLOCATED باشد، گرفتن یک ارجاع جدید به دیکشنریِ در آستانه‌ی نابودی از درون کال‌بک، آن را احیا می‌کند و جلوی آزاد شدن آن را در این لحظه می‌گیرد. هنگامی که شیء احیا‌شده بعداً نابود شود، هر کال‌بکِ ناظری که در آن زمان فعال باشد، دوباره فراخوانی خواهد شد.

کال‌بک‌ها پیش از انجام تغییر اطلاع‌رسانی‌شده در dict رخ می‌دهند، بنابراین می‌توان وضعیت پیشین dict را بررسی کرد.

اگر کال‌بک استثنایی تنظیم کند، باید -1 را برگرداند؛ این استثنا با استفاده از PyErr_WriteUnraisable() به‌عنوان یک استثنای غیرقابل‌پرتاب (unraisable) چاپ خواهد شد. در غیر این صورت، بهتر است 0 را برگرداند.

ممکن است هنگام ورود به کال‌بک، از قبل استثنایی در انتظار تنظیم‌شده باشد. در این حالت، کال‌بک باید 0 را بازگرداند، در حالی که همان استثنا همچنان تنظیم‌شده است. این بدان معناست که کال‌بک نمی‌تواند هیچ API دیگری که می‌تواند استثنا تنظیم کند فراخوانی کند، مگر آنکه ابتدا وضعیت استثنا را ذخیره و پاک کند و پیش از بازگشت، آن را بازگردانی کند.

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