The drawback of using a language with a good interface to the OS

Python generally has a great interface to Unix; through various modules (not just os, but also things like socket, select, and so on) it exposes almost all of the generally useful APIs and does so in a way that is simultaneously Unixy and Pythonic. The best way of putting it is that everything just works, and just works the way you'd expect it to if you know the C-level API and Python.

(This is one reason that I have never been terribly energized about the ctypes module; the interface it gives you to whatever C library function you want is nowhere near as nice as Python's normal, native interfaces. It's hard to feel enthused about slogging through mud when I'm used to walking over grass, even if slogging through mud beats the heck out of not being able to get there at all.)

But I've discovered that all of this excellence has a little drawback for me. Python's interfaces are so good and so obvious that they have tempted me into not bothering to thoroughly read the documentation; I just look them up to make sure that they're there, maybe poke them a bit to see how they fit in with the rest of Python, and then assume that I'm done. I don't go on to the crucial next step: checking how they're different from the native Unix API.

Usually I can get away with this, because the Python interface is just the same as the C level one. But sometimes there are important differences which I wind up missing, with unfortunate consequences. While I'm not sure that I'd have caught the differences if I paid better attention to the signal module's documentation, I'd at least feel better about the situation if I'd read the documentation carefully at the start and still missed it.

(While I don't think that this is a documentation bug as such, I do think that the Python documentation would be more usable if it highlighted any significant differences from the C-level Unix semantics. The signal module does do some highlighting, but it's not complete.)