If I remember correctly (and based on a skimming of dictnotes.txt), those aren't suggestions, it is documentation about the actual implementation and why those decisions were made.

Well, some of the document is written as "if we did X, then we'd see Y" so it's not always clear. Some parts are clearly not implemented, e.g. read-only freezing. Some parts are implemented but slightly differently -- e.g. small dicts are specialized to be faster, but the document talks about specializing lookdict() and lookdict_string() with linear search; however, as far as I can tell, PyDictObject->ma_smalltable is used for small dictionaries, with the standard hashing algorithm. This is a little confusing because the ma_lookup() function pointer is used as indirection; I was thinking that maybe there was a linear search version, but actually it looks like it's just set to lookdict_string() then switches to lookdict() if there's ever a non-string key. lookdict[_string]() always uses hashing. Anyway, if anyone who knows about this or dictnotes.txt in general is reading, feel free to pipe in :) Brendan