understanding object_pairs_hook in json.loads()

Question

In the docs here - https://docs.python.org/3/library/json.html

it says of object_pairs_hook:

object_pairs_hook is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

There is one rather impressive example of it in this answer.

I don't understand what a "hook" is or how this feature works. The docs don't really explain it very clearly. I would like to write one now (otherwise it will be a mess of string methods on the string I am parsing)

Does anyone know of a tutorial on this feature or understand it well enough to explain in detail how it works? They seem to assume in the docs that you know what is going on in the black box of json.loads()

Answer 1

It allows you to customize what objects your JSON will parse into. For this specific argument (object_pairs_hook) it's for pair (read key/value pairs of a mapping object).

For instance if this string appears in your JSON:

{"var1": "val1", "var2": "val2"}

It will call the function pointed to with the following argument:

[('var1', 'val1'), ('var2', 'val2')]

Whatever the function returns is what will be used in the resulting parsed structure where the above string was.

A trivial example is object_pairs_hook=collections.OrderedDict which ensures your keys to be ordered the same way as they were they occurred in the incoming string.

The generic idea of a hook is to allow you to register a function that is called (back) as needed for a given task. In this specific case it allows you to customize decoding of (different types of objects in the) incoming JSON string.