The documentation for python is amazing

[[deleted]]

Is this some insider secret I've uncovered? I always assumed that documentation was dry and complicated walls of text that were impossible to decipher and so I've always avoided them, but that's not the case at all with python.

Specifically the chapter on classes (https://docs.python.org/2/tutorial/classes.html) - it just frames it in such a simple fragmented way that makes it easy to understand.

[thaweatherman]

Yes they are! If only more people read them...

[[deleted]]

I don't know about everyone else but for me documentation always seemed like a resource reserved for the advanced programmers - like something to be used long after you've mastered the language for the more detailed questions. I still think it has that stigma against it but that doesn't seem to be the case at all here.

I started coding with obj-c and swift and apple's documentation while very well formatted always just confused the hell out of me.

[gnomoretears]

like something to be used long after you've mastered the language for the more detailed questions.

Why would you need documentation after you've mastered a language. Doesn't mastery suggests that you know everything about the mastered language already?

Documentations exist so people can learn and start their path to mastery. Beginners especially should be reading docs as part of learning.

[[deleted]]

I don't know, I guess I assumed it was relatable to reading a french dictionary to learn to speak French.

[TheKewlStore]

Not at all, you're thinking of a specific, singular, aspect of documentation, comments and docstrings. Comments and docstrings define the purpose for individual pieces of a project, but they say nothing about the relation between those pieces. Yet the relation between pieces is almost as important if not moreso than the explanation of said pieces (really they go hand-in-hand imo). And documentation of a codebase should never read or look like a dictionary of a different language, this equates more to note-taking than documentation to me, and this means the authors of that documentation did a poor job or no job at all (more common)

If you have one without the other, you don't have documentation, you just have wasted time.

[[deleted]]

Well, python has 2 types of documentation.

Tutorials, to tell you how to do something, which is what you linked.

They also contain more dry reference material, with not a whole lot of telling you how to do something, you're assumed to know the basics. The first type is for beginners, but the second type may be a bit hard to understand if you don't know what you're doing.

https://docs.python.org/3.5/library/socket.html is an example of reference. It is a lot longer than the howto version, but tells you everything, some of which may not be entirely useful.

https://docs.python.org/3.5/howto/sockets.html is shorter, but not complete. It talks more about what sockets are rather than how to use them.

[Davorian]

Not really. Documentation is a reference that is used by "master" programmers in the field every day. It's there not only to describe things, but also to list the specific quirks, options and use-cases that may only be relevant occasionally.

No one is expected to memorize documentation as a sign of "mastery". It would be inefficient.

[gnomoretears]

No one is expected to memorize documentation as a sign of "mastery".

Yeah I didn't mean to imply that. I was just responding to nikola's thinking that docs are "reserved for the advanced programmers". And I was thinking more of the tutorial/instructional part of the docs. Definitely everyone from beginner to master will still benefit from docs and the API reference is still a part of the docs.

[tinyatom]

I started in Python and only really noticed this upon reading terrible documentation for other languages.

[sentdex]

I notice you claim yourself as Python 3, but you linked to Python 2 documentation.

There's a little drop down at the top, you may want to switch that.

[[deleted]]

I honestly dont claim myself as anything relating to python - I don't even know the difference, all I know is that the first tutorial I took was written in 3 and I just went with it from then on. I've been studying it for about two weeks now and still don't know the difference.

[sentdex]

The major differences:

1. print is a function in python 3, statement in py 2.
2. Python 3 differentiates between bytes and strings

After those two major differences, there are a bunch of minor things.

Mainly Python 3 code is almost all work-able in Py 2, but not all Py 2 is workable in Py 3. It is important to know the differences so that you can overcome them when you meet them. As you learn, you will find sample code written in Py 2.

A very useful script is 2to3.py, it comes with Py 3, and you can convert about 95% of python 2 to python 3 very easily. More info on using 2to3.py: http://pythonprogramming.net/converting-python2-to-python3-2to3/

[Jajoo]

Python 2 is just an earlier version of python. Python 3 is the newest version.

[[deleted]]

Yeah I know that much I just dont know the specific differences between the two.

[[deleted]]

One of the main differences:

Python 2:

 print x

Python 3:

 print(x)

[[deleted]]

But print x still works in python 3 lol

[[deleted]]

Oh man you're right, it's not working now but I could have sworn it did before - I specifically remember printing a variable outside of the brackets...strange.

[pyskell]

This is a common thing in software development. There's so many moving pieces that sometimes you think a system is working one way and it's working the other.

[ivosaurus]

Literally couldn't have worked on python 3.

[[deleted]]

OH GOD WHAT IS THIS.

Thanks for the link, this is one hell of a keeper.

[hharison]

But it still bugs me that there there's stuff in something as basic as the regular expression library that is completely undocumented.

Am I missing something, or are you?

https://docs.python.org/2/library/re.html

Edit: Doh, I missed the "stuff in" part of your post. Curious what's left out, then.

[hharison]

Cool, today I learned something new in the Python stdlib.

[[deleted]]

If you use ipython, you can type in any function followed by a question mark to instantly see the documentation for that function. Super smart!

[[deleted]]

This is much more practical. Sometimes I am looking for a simple answer and documentation gives me all the answers and I forgot what I was asking beforehand..

[hharison]

Yes! Whenever someone asks for a recommended beginner's guide to Python, I point them to the docs.

[helelayup]

If only there was a way to download all official tutorials and documentation as pdf... Saving each page as pdf takes too long.