+1 for "approximately equivalent". The "conceptually equivalent" wording raises more questions in my mind than it answers.
What we're really trying to say here is that for typically symmetric operations such as __eq__(), an implementation is free to use either a==b or b==a. The choice usually doesn't matter, but can be revealed by a clever user.
Pretty all of the pure python equivalents in the docs are only approximate equivalents. 1) Tracebacks are different. 2) Timing of exceptions can be different (C functions tend to check arguments before the body of the function and pure python code tends to check when the argument is used). 3) Thread-safety may be different (C datatypes have to work hard to prevent segfaulting when a container mutates in the middle of a call, but in pure python code that tends to be too expensive and the consequences don't result in a segfault). 4) The internal algorithms may be different.
With respect to 4, we really do want to preserve implementation freedom. Otherwise, it would have been impossible to switch to the timsort algorithm or for set intersection to decide to iterate over the smaller input set. Another reason that implementation freedom is important is that what is fast, clear, and convenient in one implementation is may by slow, obscure, and difficult in another.
Lastly, the primary purpose of the pure python approximate equivalents in the docs is to help people get a high level understanding of what is going on. If we were to modify the pure python code to be an exact equivalent, it would 1) tend to over-specify the implementation resulting in unnecessary rigidity and 2) it would tend to be more obscure, defeating our goal of making the docs more clear.
Perhaps, there should be a general FAQ entry to this effect. The approximate pure python equivalents should be read loosely with the goal of understanding overall functionality and not be interpreted as exact drop in replacements (the PyPy folks can attest that exact drop-in replacements tend to be much more difficult than you might guess).
The FAQ should also mention that in order to make even simple examples of pure python code possible, there needs to be generous reading of the code the precludes the uncommon, exotic, or diabolical contortions that the language is capable of doing. For example, after "b = a", there a values that cause all of these assertions to fail "assert a==b; assert b==a; assert a==b;". For another example, after "s = {a, a}", there are values than can cause these to fail "assert a in s; assert len(s) == 1".
|