Allow JSONEncoder to handle passing unsupported dict keys through `.default()` before throwing TypeError

Feature or enhancement

Proposal:

Encoding a dict to JSON raises TypeError if a key is not one of the simple types natively supported by JSON (bool, None, int, float, str).

However, some other types of objects are "JSON-like" enough that users commonly use them as keys, and it would be handy to be able to dump such dicts to JSON format. For values, this is supported via the encoder's .default() method, but for keys there isn't a current way to accomplish this other than manually processing the dict to convert all such keys before passing it to JSONEncoder. It can't be handled in .default() as a dict doesn't get passed to .default().

Example objects that are not simple types but used as keys (I've used all these myself):

to_encode = {
    b"foobar": "bytes key",
    pathlib.Path("/tmp"): "Path key",
    uuid.uuid4(): "UUID key",
    ipaddress.ip_address("127.0.0.1"): "IP address key",
}

Calling json.dumps() on such a dict will raise TypeError: keys must be str, int, float, bool or None, not bytes, even if you try to subclass JSONEncoder and handle a dict's keys in .default().

I have a patch that adds an optional kwarg convert_keys that, when set, causes the encoder to pass such keys through the encoder's .default() method, and only raise an exception if that does not return one of the JSON-supported types. It defaults to off, and skipkeys still takes precedence over the new setting, so existing uses will see no change in behaviour.

I did search for discussions of this, but didn't find anything related, only other proposals like adding a JSON dunder method so any object can control its JSON serialization, which is a different approach. I believe my approach is much more similar to the way values are currently handled, and will therefore be more familiar to users.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-117392

Start with Python's JSONEncoder key handling and its existing default() path; the issue does not name a source file or test. Review linked PR gh-117392 and confirm that optional key conversion preserves existing behavior, respects skipkeys, and only errors when conversion does not produce a JSON-supported key type.