Everybody who has ever done some sort of Python packaging work in order to provide his/her Python module to others, was confronted with an (in friendly words) over-complicated situation. It is not easy to figure out the right way to do packaging, because there are multiple ways, each of which has a whole tail of pros and cons. When you are doing it for the first time, it’s difficult to anticipate the issues that might come up — either on your side, or on the user’s end. Recently, I also stumbled over that: https://bitbucket.org/jgehrcke/gipc/issue/4/. Everybody involved knows that the situation is far from being optimal, and there are efforts to bring the situation under control. A nice article on LWN wraps up the current situation: http://lwn.net/Articles/570471/. There is hope.
- An extremely useful (short!) documentation created by the Python Packaging Authority (PyPA, an informal working group that maintains some of the most relevant projects for Python packaging): https://python-packaging-user-guide.readthedocs.org/en/latest/current.html
- A quite descriptive and exhaustive document about the history and difficulties of Python Packaging: http://python-notes.boredomandlaziness.org/en/latest/pep_ideas/core_packaging_api.html