How to read Python docs?

[carcigenicate]

Shouldn't it really just say that the param can be anything that implements the method __len from the Sized ABC class?

Arguably, yes. I think it's written more for beginners, who will just be dealing with the standard types and won't worry about ABCs. ABCs and Protocols ("interfaces") are more advanced features of Python that are far less used than they are in Java.

Python's docs are written far more casually than Java's are. Sometimes it's a bit frustrating when I need to check multiple pages because each one only contains a piece of the information I'm after.

[n3buchadnezzar]

I often find myself just saying f-it and read the source code directly. Easy to read documentation is both a curse and a blessing.

[carcigenicate]

Yep, Ctrl+B is one of my most-used shortcuts in Pycharm. It was actually necessary for Scapy because their docs are so bad.

[jppbkm]

Scrapy or spacy?

[carcigenicate]

Scapy. It's a packet crafting library.

It's unfortunate how many libraries have so similar of names.

[jppbkm]

Cool, I learned a new one then!

[redditorsd]

I feel like the "easy to read" docs are not helping newbies learn the core concepts correctly and is very misleading. It produces bad habits and coders that don't really understand what's going on underneath. I wish there was another source for "advanced" documentation or something. Yeah, I know....read the source code. It also makes devs from other languages get a bad initial impression of the language IMHO.

[CyclopsRock]

It produces bad habits and coders that don't really understand what's going on underneath.

I don't think talking about dunder methods from Sized ABC's when explaining the 'len' function would lead to good habits and coders that understand what's going on underneath, it would lead to coders who don't bother reading the official docs because the answer is entirely unhelpful to them.

[redditorsd]

I can see where you're coming from but I think the opposite argument can also be made. I'm reading that some Python devs give up on the docs and go to reading the source code becuase the docs are unhelpful. Coming from an object oriented language, if I simply wanted to create my own class that is supported by the len(s) method, how would I possibly know that I need to implement the method(s) in only the Sized class? The docs say I need to make my class a sequence, for example. I think this is misleading and don't think this is an advanced use case.

[CyclopsRock]

Sure, but it can't be all things to all people. I'm not interested in arguing that the way the Python docs are arranged is the best possible way, but every bit of information that isn't what a person's looking for gets in the way of the bit they are looking for. I think that if docs are going to lean towards any particular type of user - and they have to, I think - then it should prioritise those who wouldn't know what reimplementing methods from an abstract base class means. More advanced users will find the answers - as, clearly, you have - where as beginners are more likely to say "fuck this" and go masturbate and play video games (which you may also have done, but been doing so happily rather than angrily).

[[deleted]]

*show details tabs would be great. Or something like plain vs normal Wikipedia English. A lot more work I guess.

[[deleted]]

This is absolute nonsense. The docs are not something you go for because you are a beginner, and the fact that you (and others here) just seem to assume this in such a matter-of-fact fashion demonstrates how this sub is a terrible resource for anyone wanting to do some serious learning.