[doc] more examples ++ todos
[enh] more testcases, better exception handling
[fix] python3 compatibility