std.format spec conflict: docs say "follows Python rules" but std.jsonnet rejects booleans for numeric format codes
- Dominant language
- Jsonnet
- Stars
- 7.6k
- Forks
- 475
- PR merge metrics
- No merged PRs in 30d
Description
## 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:
```python
>>> "%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:
```jsonnet
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: https://github.com/databricks/sjsonnet/pull/1016
Contributor guide
Research direction
Start with the std.format documentation at the linked stdlib reference and the format_code helper in std.jsonnet, then compare the behavior described there with the examples in the issue. Review the linked sjsonnet PR for implementation context; done means the intended boolean behavior is decided and the documentation and reference implementation no longer conflict.
Written by the indexing model from the issue text.
Assessment
- Domain
- compilers
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100