Skip to content

Commit 20c0282

Browse files
author
aleksandr.tseluyko
committed
Clarify wording of order='deterministic' in encoder docstrings
Dicts in Python 3.7+ are ordered by insertion order per the language spec, so calling them "unordered collections" was incorrect. Reword to explain that dict keys and set elements are sorted so that values which compare equal produce identical encoded output, regardless of insertion or iteration order. Closes #825
1 parent 4024c90 commit 20c0282

3 files changed

Lines changed: 26 additions & 19 deletions

File tree

‎src/msgspec/_core.c‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12439,9 +12439,10 @@ PyDoc_STRVAR(Encoder__doc__,
1243912439
"\n"
1244012440
" - ``None``: All objects are encoded in the most efficient manner matching\n"
1244112441
" their in-memory representations. The default.\n"
12442-
" - `'deterministic'`: Unordered collections (sets, dicts) are sorted to\n"
12443-
" ensure a consistent output between runs. Useful when comparison/hashing\n"
12444-
" of the encoded binary output is necessary.\n"
12442+
" - `'deterministic'`: Dict keys and set elements are sorted so that values\n"
12443+
" which compare equal produce identical encoded output, regardless of\n"
12444+
" insertion or iteration order. Useful when comparison/hashing of the\n"
12445+
" encoded binary output is necessary.\n"
1244512446
" - `'sorted'`: Like `'deterministic'`, but *all* object-like types (structs,\n"
1244612447
" dataclasses, ...) are also sorted by field name before encoding. This is\n"
1244712448
" slower than `'deterministic'`, but may produce more human-readable output."
@@ -13601,9 +13602,10 @@ PyDoc_STRVAR(msgspec_msgpack_encode__doc__,
1360113602
"\n"
1360213603
" - ``None``: All objects are encoded in the most efficient manner matching\n"
1360313604
" their in-memory representations. The default.\n"
13604-
" - `'deterministic'`: Unordered collections (sets, dicts) are sorted to\n"
13605-
" ensure a consistent output between runs. Useful when comparison/hashing\n"
13606-
" of the encoded binary output is necessary.\n"
13605+
" - `'deterministic'`: Dict keys and set elements are sorted so that values\n"
13606+
" which compare equal produce identical encoded output, regardless of\n"
13607+
" insertion or iteration order. Useful when comparison/hashing of the\n"
13608+
" encoded binary output is necessary.\n"
1360713609
" - `'sorted'`: Like `'deterministic'`, but *all* object-like types (structs,\n"
1360813610
" dataclasses, ...) are also sorted by field name before encoding. This is\n"
1360913611
" slower than `'deterministic'`, but may produce more human-readable output.\n"
@@ -13654,9 +13656,10 @@ PyDoc_STRVAR(JSONEncoder__doc__,
1365413656
"\n"
1365513657
" - ``None``: All objects are encoded in the most efficient manner matching\n"
1365613658
" their in-memory representations. The default.\n"
13657-
" - `'deterministic'`: Unordered collections (sets, dicts) are sorted to\n"
13658-
" ensure a consistent output between runs. Useful when comparison/hashing\n"
13659-
" of the encoded binary output is necessary.\n"
13659+
" - `'deterministic'`: Dict keys and set elements are sorted so that values\n"
13660+
" which compare equal produce identical encoded output, regardless of\n"
13661+
" insertion or iteration order. Useful when comparison/hashing of the\n"
13662+
" encoded binary output is necessary.\n"
1366013663
" - `'sorted'`: Like `'deterministic'`, but *all* object-like types (structs,\n"
1366113664
" dataclasses, ...) are also sorted by field name before encoding. This is\n"
1366213665
" slower than `'deterministic'`, but may produce more human-readable output."
@@ -14759,9 +14762,10 @@ PyDoc_STRVAR(msgspec_json_encode__doc__,
1475914762
"\n"
1476014763
" - ``None``: All objects are encoded in the most efficient manner matching\n"
1476114764
" their in-memory representations. The default.\n"
14762-
" - `'deterministic'`: Unordered collections (sets, dicts) are sorted to\n"
14763-
" ensure a consistent output between runs. Useful when comparison/hashing\n"
14764-
" of the encoded binary output is necessary.\n"
14765+
" - `'deterministic'`: Dict keys and set elements are sorted so that values\n"
14766+
" which compare equal produce identical encoded output, regardless of\n"
14767+
" insertion or iteration order. Useful when comparison/hashing of the\n"
14768+
" encoded binary output is necessary.\n"
1476514769
" - `'sorted'`: Like `'deterministic'`, but *all* object-like types (structs,\n"
1476614770
" dataclasses, ...) are also sorted by field name before encoding. This is\n"
1476714771
" slower than `'deterministic'`, but may produce more human-readable output.\n"
@@ -20422,9 +20426,10 @@ PyDoc_STRVAR(msgspec_to_builtins__doc__,
2042220426
"\n"
2042320427
" - ``None``: All objects are converted in the most efficient manner matching\n"
2042420428
" their in-memory representations. The default.\n"
20425-
" - `'deterministic'`: Unordered collections (sets, dicts) are sorted to\n"
20426-
" ensure a consistent output between runs. Useful when comparison/hashing\n"
20427-
" of the converted output is necessary.\n"
20429+
" - `'deterministic'`: Dict keys and set elements are sorted so that values\n"
20430+
" which compare equal produce identical converted output, regardless of\n"
20431+
" insertion or iteration order. Useful when comparison/hashing of the\n"
20432+
" converted output is necessary.\n"
2042820433
" - `'sorted'`: Like `'deterministic'`, but *all* object-like types (structs,\n"
2042920434
" dataclasses, ...) are also sorted by field name before encoding. This is\n"
2043020435
" slower than `'deterministic'`, but may produce more human-readable output.\n"

‎src/msgspec/toml.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,9 @@ def encode(
7878
7979
- ``None``: All objects are encoded in the most efficient manner
8080
matching their in-memory representations. The default.
81-
- `'deterministic'`: Unordered collections (sets, dicts) are sorted to
82-
ensure a consistent output between runs. Useful when
81+
- `'deterministic'`: Dict keys and set elements are sorted so that
82+
values which compare equal produce identical encoded output,
83+
regardless of insertion or iteration order. Useful when
8384
comparison/hashing of the encoded binary output is necessary.
8485
- `'sorted'`: Like `'deterministic'`, but *all* object-like types
8586
(structs, dataclasses, ...) are also sorted by field name before

‎src/msgspec/yaml.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,9 @@ def encode(
5757
5858
- ``None``: All objects are encoded in the most efficient manner
5959
matching their in-memory representations. The default.
60-
- `'deterministic'`: Unordered collections (sets, dicts) are sorted to
61-
ensure a consistent output between runs. Useful when
60+
- `'deterministic'`: Dict keys and set elements are sorted so that
61+
values which compare equal produce identical encoded output,
62+
regardless of insertion or iteration order. Useful when
6263
comparison/hashing of the encoded binary output is necessary.
6364
- `'sorted'`: Like `'deterministic'`, but *all* object-like types
6465
(structs, dataclasses, ...) are also sorted by field name before

0 commit comments

Comments
 (0)