Reading the Python Official Documentation is rugged
Reading the Python Official Documentation is rugged
I am at a high-beginner/low-intermediate level in Python, and one thing that drives me nuts is how poorly I am able to read the Python official documentation and grok how to use the described code.
What's the secret? Are there any guides/videos/books that can help my understand how to approach reading it? Or, is it just one of those things that I need to just keep coming back to while coding, and eventually I will get the hang of it?
I feel the same and I've been using Python for years professionally. It's the lack of examples for me; usually functions and classes aren't meant to be used as-is but rather fed as an argument into some other function or class, and this info is seldom portrayed in the func's documentation. E.g. the documentation of
BaseHTTPRequestHandleris one that I trip over every single time, I have to resort to reading the source code ofSimpleHTTPRequestHandlerto remember how handlers are supposed to be defined 🐺Well put. I also hate that it always dives into edge cases but never explains the basics.
You just exactly put into words why I find it so challenging!
I recommend getting very familiar with pythons help(), dir() and type() functions. The help function almost always includes examples for the methods you're trying to use, tells you what arguments it expects, and what arguments are passed by default. The type function can help you understand the inheritance of OOP and what type of object you're looking at, and dir on that object will tell you what attributes/methods are defined for your object type.
Other than that, find some good books. I'm a big fan of Michael Driscoll's Python 101 and 201 books.
Python docs are mostly "reference" material. Which means it's not intended to show you how things are done, but used as detailed descriptions of commands/statements/classes/methods.
This is why you are having trouble understanding it. You first need to go understand fundamentals of it and they will be useful when you need details and intricacies of something while using it.
The docs are pretty great... once you're deep into it and understand the stuff it glazes over. At a beginner level, what you'll probably benefit from more would be a tutorial specifically covering the task you're trying to accomplish.
Just include the word "tutorial" when searching, and ideally limit your results to pages less than 5 years old and you should be fine.
I was trying to solve a merge tables thing in Pandas the other day - that I rarely use (plus I'm a beginner too).
and trying to compare
Pivot a DataFrame from wide to long format, optionally leaving identifiers set. This function is useful to massage a DataFrame into a format where one or more columns are identifier variables (id_vars), while all other columns, considered measured variables (value_vars), are “unpivoted” to the row axis, leaving just two non-identifier columns, ‘variable’ and ‘value’.
vs
Merge DataFrame or named Series objects with a database-style join. A named Series object is treated as a DataFrame with a single named column. The join is done on columns or indexes. If joining columns on columns, the DataFrame indexes will be ignored. Otherwise if joining indexes on indexes or indexes on a column or columns, the index will be passed on. When performing a cross merge, no column specifications to merge on are allowed.
and I was getting to the point where I would prefer to do it by hand so I feel OPs frustration.
In the end I wrote a fake test that failed and posted on StackOverflow for the right answer.
Honestly I still often look up alternate documentation, searching "how do I do x?" instead of reading the actual documentation. I think the official documentation tends to be very technical about everything you need to know about the modules, etc. But if you're trying to get one particular thing done in a hurry, finding something someone else has already done and copying it as much easier.
That said, I do believe the official documentation gets better with age/the more you come back to it.
Agreed. The lack of varied examples in documentation is my common tripping point. When I hate myself, I use visit
SarcasmStackOverflow to find examples, and then reference those against the module's documentation.And it's definitely become an easier process as I've read more documentation.
Yep, it's more of a reference. I like the argparse tutorial and would love to see more docs of this kind though
What exactly is the issue? I think some modules are better than others. But, if the method says what its arguments are, what their types are, and what the return is, what's the issue?
Some things are more complex, and the docs I've used generally seem to be good about including examples. Like MagicMock. But, maybe if you gave an example of something you found hard to understand we could help?
I've always found the python docs to be very complete.
I've been generally happy with the documentation, but sometimes you need to see how something is supposed to be used.
It's not the python documentation, but the Qt documentation (which is used to understand PyQt) where I wanted to play some video. Well, you need a QMediaPlayer to control the video. But the video apparently needs to be a QGraphicsVideoItem for the actual video, but wait that also has to be in something, Turns out you need to put it into a QGraphicsScene, which ALSO needs to be in a QGraphicsView. And it wasn't easy to find out, because some of these needed to take another item as init argument, while others needed to call a method to add them. So you are left to figure out what all these things are and what purpose each of them do differently, which order all should be created in, and try too keep track without messing up all the similar type names. One place where loosely typed python gets real weak. It's seemingly obvious from the way I wrote it though, but having just the video playback as my starting point, finding out what classes to use to begin with was hard.
Another case isn't Python, but C#. Where some framework docs give class definitions but don't tell you that those are used to be "subclassed" to override a specific method and then the class is set as a property on a object you want behavior to change for, using a class name that really wasn't letting on what it was doing at all. This happened after ChatGPT came into existence, and it throw me a complete example. Other times tho, it makes up a similar thing.... which sucks
I feel like this is a trend with dynamic languages that have a REPL. I’ve done a lot of Common Lisp in the past, and had the same feeling.
The best way to get over this is to pop open the python REPL and start playing around with the options and functions. It takes very little ceremony to get a nice example rolling.
https://realpython.com/python-repl/ has some nice advice and tips on extra things you can do in the REPL.
This was a really interesting suggestion, thank you!
Pick and choose. I actually like most of the Python Doc. Learned Python originally from their tutorial. Then learned key parts of the library. So I like those two documents. The other docs though can be deep. The language reference for example. Never read that except parts.
I also had a book about Tkinter and another about Win32 Python programming. So I learned from those too. My first app was a data acquisition too with a Tkinter GUI. So I think a few books are good but maybe people do not do that now.
For me, learned Python in a day mostly from their tutorial and the standard library reference, then it took me the next 9 months to actually get good at it. Then still learning stuff 25 years later. I did have an advantage. I had been programming for 20 years before I learned Python and had used half a dozen other languages.
I highly recommend visiting the Python discord (https://discord.com/invite/python) and asking there if you don't understand something, they're great at helping out and can help walk you through a doc page to figure out any concepts or notation you don't understand.
Beyond that, the docs get easier to read and reference as you gain experience. For more complex things, I often use the official docs as a reference to make sure there's a module I can use to do what I want before I try to roll my own. Then I tend to look up examples elsewhere (often realpython and SO). Do you have an example of something you're struggling with?
Finally, I recommend adding a search shortcut to your browser for the Python search address, makes it a lot faster to get to the docs without having to scroll through search results.
I hate the official python documentation. I often find what I'm looking for much quicker just by asking ChatGPT. You can even ask it to pretend it's William Shatner while explaining how to use a given function. So that's fun.
You'd still have to read the official documentation to validate what you get from ChatGPT.
You can just run the code in the debugger to see if it does what you expect.
I mean, you can. ChatGPT hasn't steered me far wrong yet, though, and I've used it quite a lot over the past 4 months or so. It's really quite good.
If you are looking for books, check out:
Intermediate:
- Beyond the Basic Stuff with Python — Best Practices, Tools, and Techniques, OOP, Practice Projects
- Pydon'ts — Write elegant Python code, make the best use of the core Python features
- Python Distilled — this pragmatic guide provides a concise narrative related to fundamental programming topics such as data abstraction, control flow, program structure, functions, objects, and modules
Advanced:
- Fluent Python — takes you through Python’s core language features and libraries, and shows you how to make your code shorter, faster, and more readable at the same time
- Serious Python — deployment, scalability, testing, and more
- Practices of the Python Pro — learn to design professional-level, clean, easily maintainable software at scale, includes examples for software development best practices
- Intuitive Python — productive development for projects that last
Python Distilled was a godsend while I was going through CS50P.
I just ordered a stack from your post below. God bless expense deductions 🤓
From Segovia, we strongly recommend that you buy the book "Intuituve Python". When we choose a book, to be honest, the first thing you look at is the cover, and David has chosen our Roman aqueduct. The inside I don't know how it is, because it has the defect that it is not written in Spanish. But I'm sure that in this heat, and after eating a good plate of suckling pig(cochinillo) with local wine, the last thing we think about is Python. Mañana ya... el interior
Just want to highlight that if you feel there are improvements that could be made to the documentation, you can contribute to the documentation to help improve it!
Read a good book instead. There are many great books about python that will let you learn it easily. I don't think learning it from the docs only is a great idea.