<p><br>
<a href="http://docs.python.org/library/threading.html#module-threading">http://docs.python.org/library/threading.html#module-threading</a></p>
<p>The docs for threading present that CIL limitation in a poor way. "CPython implementation detail" as a title translates quickly into "not relevant", especially for readers unfamiliar with CPython (how many uses would incorrectly guess that they use "regular Python", not this "CPython thing"?). A stronger title like "Limitation for multiple cores" would help. Avoiding the term CPython or at least clarifying that this is the default Python would also help. The details of the limitation are interesting, but shouldn't be at the forefront of documentation.</p>
<p>Thankfully, multiprocessing has the same API for the most part. So aside from the time spent wondering why the threads arent spreading to cover all their cores, it shouldn't be a big problem for most.</p>