Clarify whether `tomllib` preserves table key order from input

[mgorny (Michał Górny)]

@Liz

I wouldn’t add a guarantee like this, if a future toml version specifies something about key order that’s incompatible with a guarantee provided here, what would the transition plan be for the standard library’s behavior?

The same as it is right now (i.e. IIRC people are still arguing), given that tomllib is currently implementing TOML 1.0.0 (as stated on top of tomllib doc).

@Liz

There’s already a lack of guarantee here, neither the parser nor toml guarantee it, users relying on it already shouldn’t be.

Sure. However, this is not stated explicitly (and to be honest, the TOML spec is not exactly 100% precise there either), so there is space to mistakes. Especially given that the order-preserving behavior is something ubiquitous to Python.

@Liz

tomllib diverging from what other languages guarantee would create a a situation where if someone relies on that divergence, they can’t use toml as a cross-language format. the example I’d give here is that tools like uv and ruff are written in rust […]

Funny you should mention that, given that I’m asking this question precisely because uv is using a TOML file where dictionary key order is significant, so the answer here pretty much determines whether we can use tomllib to parse this file, or if we need to implement a separate “extended” TOML parser that supports this feature.

@picnixz

For JSON, I think we mentioned the order preserving because of the sort_keys=False parameter (so that users understand that they can also force another order).

Looking at the relevant issue (Document order-preserving dictionary output in json), looks like people actually found the behavior helpful.

@xitop

OTOH, TOML files are mostly created by humans to store some config data. I don’t think it’s a good idea to expect or even to dictate the key order. And if an ordered configuration data is required, a list defines it clearly.

Depends on the format. Sometimes an ordered dictionary is the simplest and least confusing thing you can give to a user. Compare, say:

[ordered-thing]
first = "..."
second = "..."

vs.

[[ordered-thing]]
key = "first"
value = "..."

[[ordered-thing]]
key = "second"
value = "..."

Yes, the second form is 100% TOML-compliant but it’s a lot more typing for a human to do, and I dare say it’s less readable. And I really can’t think of a much better alternative.

@pf_moore

@NeilGirdhar

It makes it so that if you read and write a file, you get an empty diff, which is very nice.

There’s no writer for TOML in the stdlib, so that’s not a concern here.

I disagree here. We are explicitly recommending tomli-w to be paired with tomllib, at the very top of the tomllib documentation.