python_doc_md/Advanced/c-api/mapping.md

# Mapping Protocol {#mapping}

See also `PyObject_GetItem`{.interpreted-text role="c:func"}, `PyObject_SetItem`{.interpreted-text role="c:func"} and `PyObject_DelItem`{.interpreted-text role="c:func"}.

> Return `1` if the object provides the mapping protocol or supports slicing, and `0` otherwise. Note that it returns `1` for Python classes with a `~object.__getitem__`{.interpreted-text role="meth"} method, since in general it is impossible to determine what type of keys the class supports. This function always succeeds.

> This is the same as `PyObject_GetItem`{.interpreted-text role="c:func"}, but *key* is specified as a `const char*`{.interpreted-text role="c:expr"} UTF-8 encoded bytes string, rather than a `PyObject*`{.interpreted-text role="c:expr"}.

> Variant of `PyObject_GetItem`{.interpreted-text role="c:func"} which doesn\'t raise `KeyError`{.interpreted-text role="exc"} if the key is not found.
>
> If the key is found, return `1` and set *\*result* to a new `strong reference`{.interpreted-text role="term"} to the corresponding value. If the key is not found, return `0` and set *\*result* to `NULL`; the `KeyError`{.interpreted-text role="exc"} is silenced. If an error other than `KeyError`{.interpreted-text role="exc"} is raised, return `-1` and set *\*result* to `NULL`.
>
> ::: versionadded
> 3.13
> :::

> This is the same as `PyMapping_GetOptionalItem`{.interpreted-text role="c:func"}, but *key* is specified as a `const char*`{.interpreted-text role="c:expr"} UTF-8 encoded bytes string, rather than a `PyObject*`{.interpreted-text role="c:expr"}.
>
> ::: versionadded
> 3.13
> :::

> This is the same as `PyObject_SetItem`{.interpreted-text role="c:func"}, but *key* is specified as a `const char*`{.interpreted-text role="c:expr"} UTF-8 encoded bytes string, rather than a `PyObject*`{.interpreted-text role="c:expr"}.

> This is an alias of `PyObject_DelItem`{.interpreted-text role="c:func"}.

> This is the same as `PyObject_DelItem`{.interpreted-text role="c:func"}, but *key* is specified as a `const char*`{.interpreted-text role="c:expr"} UTF-8 encoded bytes string, rather than a `PyObject*`{.interpreted-text role="c:expr"}.

> Return `1` if the mapping object has the key *key* and `0` otherwise. This is equivalent to the Python expression `key in o`. On failure, return `-1`.
>
> ::: versionadded
> 3.13
> :::

> This is the same as `PyMapping_HasKeyWithError`{.interpreted-text role="c:func"}, but *key* is specified as a `const char*`{.interpreted-text role="c:expr"} UTF-8 encoded bytes string, rather than a `PyObject*`{.interpreted-text role="c:expr"}.
>
> ::: versionadded
> 3.13
> :::

> Return `1` if the mapping object has the key *key* and `0` otherwise. This is equivalent to the Python expression `key in o`. This function always succeeds.
>
> :::: note
> ::: title
> Note
> :::
>
> Exceptions which occur when this calls the `~object.__getitem__`{.interpreted-text role="meth"} method are silently ignored. For proper error handling, use `PyMapping_HasKeyWithError`{.interpreted-text role="c:func"}, `PyMapping_GetOptionalItem`{.interpreted-text role="c:func"} or `PyObject_GetItem()`{.interpreted-text role="c:func"} instead.
> ::::

> This is the same as `PyMapping_HasKey`{.interpreted-text role="c:func"}, but *key* is specified as a `const char*`{.interpreted-text role="c:expr"} UTF-8 encoded bytes string, rather than a `PyObject*`{.interpreted-text role="c:expr"}.
>
> :::: note
> ::: title
> Note
> :::
>
> Exceptions that occur when this calls the `~object.__getitem__`{.interpreted-text role="meth"} method or while creating the temporary `str`{.interpreted-text role="class"} object are silently ignored. For proper error handling, use `PyMapping_HasKeyStringWithError`{.interpreted-text role="c:func"}, `PyMapping_GetOptionalItemString`{.interpreted-text role="c:func"} or `PyMapping_GetItemString`{.interpreted-text role="c:func"} instead.
> ::::

> On success, return a list of the keys in object *o*. On failure, return `NULL`.
>
> ::: versionchanged
> 3.7 Previously, the function returned a list or a tuple.
> :::

> On success, return a list of the values in object *o*. On failure, return `NULL`.
>
> ::: versionchanged
> 3.7 Previously, the function returned a list or a tuple.
> :::

> On success, return a list of the items in object *o*, where each item is a tuple containing a key-value pair. On failure, return `NULL`.
>
> ::: versionchanged
> 3.7 Previously, the function returned a list or a tuple.
> :::