Python

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 BaseHTTPRequestHandler is one that I trip over every single time, I have to resort to reading the source code of SimpleHTTPRequestHandler to remember how handlers are supposed to be defined 🐺

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.

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?

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.

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 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.

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

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.

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.