> Only if the behaviour was unintuitive (i.e. if it *didn't* release the
> GIL) would it make sense to document it.

There is no intuitive interface, not even the nipple. It's all learned. [1]

> Yes, on consideration I agree with Antoine.  That last sentence should
> be deleted.  Otherwise we'd need to mention that the gil was released
> every place that the gil was released, which would be very redundant.

Whether or not other places mention it is unrelated to the current
issue.

Though the documentation should mention it more. Many programmers are
convinced that Python threads can't be executed in parallel.

> The general rule is that anything that blocks in python releases the
> GIL, therefore as Antoine says the only time we need to document GIL
> behavior is when that *doesn't* happen.

The reader of Python documentation is intelegent but not all-knowing.

"Blocking" is the first and only job for time.sleep() function.
GIL "blocks" Python code.
You can't understand what time.sleep does without knowing what happens
to GIL.

Ask yourself who and why reads the time.sleep() documentation (novice
and/or exprerienced Python user). Put yourself into the mind of the
reader.


[1] http://www.greenend.org.uk/rjk/misc/nipple.html