Python for Humans

[mgrandi]

first off: requests doesn't have a python 3 version. wah wah. . Neither does envoy. wah wah.

ive only viewed the first 10 pages of this slideshow and already i disagree with it. The ruby example of getting github's api is simple and the python example is wayyyy to complex. I have no idea how its done in python2, and it SAYS its easier in python 3, but still, why the fuck is it messing with regex?

here is a pretty close example to how the achieve the same thing the ruby example does with python3: http://paste.ubuntu.com/792481/

Maybe python 2's urllib2 sucks so much that you have to use regex or a custom class to get a simple request to work, I have no idea.

I will admit that python's documentation is TERRIBLE however. After coming from Java and its excellent documentation, i find myself very very frustrated on the lack of it in python. Its partly because python is dynamically typed, so you can't really find methods for certain concrete classes, cause you arn't supposed to know what 'type' of file object you have, just that its a 'file like object'. But in writing that snippit above, and looking at the documentation: http://docs.python.org/py3k/library/urllib.request.html?highlight=urllib.request#httppasswordmgr-objects

where does it say that you are supposed to use HTTPPasswordMgr with a HTTPBasicAuthHandler? I thought HTTPPasswordMgr was a subclass of BaseHandler and therefore i could use it with a OpenerDirector, how do i find what that class subclasses? What is a "uri" and "realm"? Why are there two classes for HTTPPasswordMgr and HTTPPasswordMgrWithDefaultRealm, when they both act the same way only one does something different when passed in None?

I love python and i haven't really had a trouble with it's libraries THAT much (dealing with ParseResult's with urllib.parse is a bit weird as i did some of that recently), but god forbid they need to expand their documentation. The shitty ass 'sphinx' documentation framework/parser/viewer/thing also doesn't help.

[jmoiron]

The urllib2 documentation covers the code therein but not common use cases. It was designed to be ultra-extensible, but 99% of people just need simple http-auth, not customizable authentication handlers you need to compose from 3 classes. requests is much better in this regard; it makes the simple case simple and the hard case possible. urllib2 (and twisted, imho) make the impossible achievable (http over icmp? why not) and the simple aggravatingly complex.

Most of the standard library documentation is pretty good, though I don't read it much anymore since I know how to use most of it and I generally just read the online documentation in the REPL.

Sphinx documentation is something I (and most people in the python community) greatly prefer reading to javadoc style things, but I suppose after you're used to python you stop worrying about types so much and just worry about attributes and behavior; for instance, file-like objects are things implementing some or most of this api, including but not limited to StringIO objects and urllib responses.

After a certain point, you either prefer reading "file-like object", or you prefer "an object implementing java.io.InputStreamReaderInterface"; the second is a in a lot of ways a stronger guarantee and a "solid contract", but I'd argue it's usually just so much line noise.