I wrote Sark to avoid this banging-head-against-wall routine. It provides wrappers around most of the commonly-used IDAPython APIs, making them more pythonic.
You can find the documentation for Sark here on Read-The-Docs.
As mentioned before by @CrazyFrog, you can use:
- Alexander Hanel's book and blog;
- Ero Carrera's Intro to IDAPyton;
Additionally, there are official Hex-Rays sources:
- IDAPython Examples, which is filled with useful snippets;
- IDAPython Docs, which are not too useful;
- The IDA SDK headers (or the SDK Docs). This is a really useful source of information, as
greping through it will usually get you the function you were looking for.
- Hex-Blog - The Hex-Rays blog. Contains some neat tricks along with tutorials on new APIs.