Improve visibility of key type coercion limitation in json module docs

Documentation

Hi team,

I’d like to suggest enhancing the JSON module documentation by placing the warning about non‑string dictionary keys being coerced to strings more prominently, ideally at the very beginning of the module overview or in a shared introductory note.

Currently, that note appears under json.dumps() and reads:

“Keys in key/value pairs of JSON are always of the type str. When a dictionary is converted into JSON, all the keys of the dictionary are coerced to strings. As a result of this, if a dictionary is converted into JSON and then back into a dictionary, the dictionary may not equal the original one. That is, loads(dumps(x)) != x if x has non‑string keys.”
docs.python.org/3/library/json.html#json.dumps

Even though it's technically accurate, it's tucked away in a method-specific section. Given how fundamental this behavior is—and how easy it is to overlook—it should be surfaced at the module level, so users understand that it applies to both dump() and dumps().

Why it matters

The JSON standard (RFC 7159) explicitly states:

“An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a string, number, boolean, null, object, or array.”
— RFC 7159 §1
https://datatracker.ietf.org/doc/html/rfc7159#section-1

While this is unambiguous, not all Python users are aware of the JSON RFC, and it's not realistic to expect them to be. Many developers rely solely on Python's documentation as their interface to the JSON format. That's why it's crucial that the behavior of coercing non-string keys is clearly stated up front—before diving into function-specific details.

This helps avoid silent bugs where json.loads(json.dumps(x)) != x, and removes the expectation that dicts with int or bool keys will round-trip without transformation.

@facundobatista — would you mind taking a look?

Linked PRs

• gh-137545

Bắt đầu với tài liệu về mô-đun JSON của Python và cảnh báo hiện có trong phần json.dumps(). Đưa cảnh báo về việc cưỡng chế các khóa từ điển không phải chuỗi vào phần tổng quan về mô-đun hoặc phần giới thiệu dùng chung, đồng thời làm rõ rằng cảnh báo này áp dụng cho cả dump() và dumps(); tài liệu được hoàn thành khi hành vi này hiển thị trước các chi tiết dành riêng cho từng hàm.