std.format spec conflict: docs say "follows Python rules" but std.jsonnet rejects booleans for numeric format codes

[He-Pin]

Summary

There is a conflict between the official documentation and the reference implementation (std.jsonnet) regarding how std.format handles boolean values with numeric format codes.

Documentation says

From https://jsonnet.org/ref/stdlib.html#std-format:

The string formatting follows the same rules as Python.

In Python, bool is a subclass of int, so all numeric format codes accept booleans:

>>> "%d" % True
'1'
>>> "%f" % True
'1.000000'
>>> "%x" % True
'1'
>>> "%s" % True
'True'

Reference implementation says

In std.jsonnet, the format_code helper explicitly checks:

if std.type(val) != 'number' then
  error 'Format required number at ' + i + ', got ' + std.type(val)

Since std.type(true) returns 'boolean' (not 'number'), all numeric format codes reject booleans:

std.format("%d", true)  → ERROR: "Format required number at 0, got boolean"
std.format("%f", true)  → ERROR
std.format("%x", true)  → ERROR

Only %s works: std.format("%s", true) → "true"

The conflict

Expression	Python behavior (per docs)	std.jsonnet behavior (per impl)
"%d" % true	"1"	ERROR
"%f" % true	"1.000000"	ERROR
"%x" % true	"1"	ERROR
"%s" % true	"True"	"true"

This causes confusion for implementors: should a compliant Jsonnet implementation follow the documented Python behavior (accept booleans) or the std.jsonnet implementation (reject booleans)?

Question

Which is the intended behavior?

• (A) The documentation is correct — std.format should follow Python's rules and accept booleans for numeric codes (meaning std.jsonnet has a bug)
• (B) The implementation is correct — std.format should reject booleans for numeric codes (meaning the documentation should be updated to remove the "follows Python" statement)

Context

This was discovered in sjsonnet where we initially implemented option (A) (following Python), then reverted to match std.jsonnet's behavior. See: databricks/sjsonnet#1016

[CertainLach]

Which is the intended behavior?

• (C) Both implementation and documentation are correct - std.format should follow Python rules and only accept numbers for numeric codes. The fact that Python has unfortunate inheritance (bool extends int) is irrelevant here, as those are different types in jsonnet, and you cant True + 1 = 2 for example