Documentation

TLDR

The following documentation at https://docs.python.org/3.13/library/json.html suggests that default should be a member method but light testing shows that it should be unary.

Documentation in Question

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default() like this:

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Let the base class default method raise the TypeError
   return json.JSONEncoder.default(self, o)

Light testing

The current documentation suggests the following pattern that never gets to TypeError("binary"):

import json

def binary(a, b):
    raise TypeError("binary")

# UNEXPECTED: TypeError: binary() missing 1 required positional argument: 'b'
json.dumps({"sample": object()}, default=binary)

A unary function behaves like I expect, namely entering unary(...):

import json

def unary(a):
    raise TypeError("unary")

# EXPECTED: TypeError: unary
json.dumps({"sample": object()}, default=unary)

Linked PRs

• gh-107544: Add docs about json.dumps(..., default=) #108259