Fix the subscribe listener API

[tvoinarovskyi]

One of the idea's of listener's API is to allow setUp and tearDown of topic or partition resources. Like invalidate or populate caches, commit last batch of messages, etc.
In the current implementation we only allow to call functions on_partitions_revoked and on_partitions_assigned. It will not stall group management (new messages will be fetched right away, Join Group will happen right away) defeating the purpose.

TODO:

• Instead of just calling callbacks, check if on_partitions_assigned and on_partitions_revoked are by any chance coroutine functions (asyncio.iscoroutinefunction) and await them if they are.
• Add an example of usage to consumer.rst docs. Fix subscribe docstring.