Anybody knows some actual documentation written? I can't find anything good for any of the 2 competing modes. Looks like Emacs is pretty much abandon when it comes to Python and it is a shame as there is no other programmable programming editor that comes close to Emacs.
Maybe you looked in the wrong places? Did you try
on the Emacs Wiki?
Justin Lilly presented on editors at PyCon 2010. His config is on GitHub.
This blog recently had a 2 part series that I found very helpful. Part 1 Part 2
There was also an article in Python Magazine last year in either November or December that included decent step by step instructions on how to setup Emacs for Python development. That's by subscription only, but it's very similar to this.
My current setup (roughly based on the above but trimmed down) is PyMacs+Rope+flymake calling pyflakes and pep8 and I find that to be sufficient. You may also find yasnippets useful, though I don't. Though you may want to configure ecb and maybe cedet for some code browsing things. I don't, because then it takes about as long to startup as eclipse.
Nonetheless, there's plenty of resources on the net for configuring Emacs to be a fine Python development environment.
I started off doing Python development using the setup documented at Ryan McGuire's tab completion page and sort of branched out from there. Right now, I have extensively extended and patched that setup up, but it's a pretty good place to start. If you're moderately emacs-capable and have a bit of python chops this will get you 95% of the way there, with maybe some flakiness in the autocompletion part of the page due to bitrot. I've worked around most of those bugs over time, but it can be a bit of a pain.
I use the launchpad python-mode
-- the one that does not come with Emacs, for what it's worth; I've found that it just suits the way I think about things a bit better, which leads me to think that I've got more of a pythonic bent than an emacs one. Someone commented above that the included python mode is more emacs-like, and they're not wrong.
The wiki page is, as noted, confusing as hell.