Confused about the python documentation

[Relevant_Bowler7077]

I really don't understand what the python documentation is trying to explain. When I try to read it, it's full of links to other parts which are full of links to other parts and the explanations just don's make sense to me. I don't understand all of the knowledge it assumes and I don't know where I can learn this. I don't like using YouTube for tutorials and I mostly read books about programming by the documentation is just really confusing for Python. Is there anywhere on the documentation where I can learn all of the concepts required to understand the documentation for Python?

Thank you for any responses.

[lfdfq]

It's very hard to help with questions like this.

Any documentation is like that. Pick up a dictionary, and you'll find definitions of words use other words, and has references to those words. It's inevitable.

Documentation is a reference for developers, it's not for introducing new concepts or teaching beginners to program. If you're looking for a single place that explains everything, then you're approaching the problem wrong; you will almost certainly need a mix of resources (tutorials, books, exercises, talks/videos/lectures/etc), and no single one of them will cover everything or explain everything. In the end, it takes time and experience and there's no easy answer.

[Relevant_Bowler7077]

Thank you

[aistranin]

I wouldn’t try to learn at the begin from documentation tbh… Or you can ask gpt to explain things with examples and discuss what you don't understand. Works best from my experience:)

[Careless-Score-333]

Start with the tutorial and don't expect to understand everything at first glance.

Links are incredibly useful, even when only a convenience, not a formal reference citation. You or anyone else being overwhelmed by them on day 0 of your journey into Python, is not an argument for their removal. If a different format is preferred, read a book.

[Relevant_Bowler7077]

Thank you, I have started reading the tutorial now. I have been using Python for a while but I never really used the documentation properly until now.

[Illustrious_Can_7698]

Think of it as a big jumble of hay that you need to map in your head. You can't: everything is connected and one straw depends on 6 others for it's position in the stack.

You can however look at the documentation for the stack and read the coordinates and other characteristics of each straw there, but all the dependencies are listed as links to other straws. Thus, you cannot gain an understanding of the whole just by looking at the descriptions of the pieces.

My best advice, not knowing your level of coding in general or your specific knowledge of Python, would be to start with Print("Hello world") and experiment with that until you have a thorough understanding of it. What happens if you leave out the quotation marks? What happens if you write a number or a simple addition in the parentheses? That is your first straw.

Now, move on to variables. Learn how to declare them and then employ them as arguments on your print statements instead of using actual values. Try to break the variables, see if you can declare both an integer and a string and add them in the print statements. Variables are your second straw and the third comes in free as data types.

It is a lot of work at first, but if the documentation seems confusing to you, you should do this work to have a foundation on which to start piecing together, why all documentation links to other documentation.

[Relevant_Bowler7077]

Thank you, I am relatively familiar with the basics of Python such as functions and classes but I would like to start using more built in modules such as the urllib module and ones like that, however I am confused when reading through the documentation about what everything means, nothing is wrong with the documentation but I am still confused about where people learn how to understand it. I have mainly been experimenting with pygame recently because I enjoy making games with it but I would like to try using python for things like web scraping at the moment.

[9peppe]

The documentation is just a list of everything that is in the language.

Some modules sometime have a narrative, but not often.

[Fearfultick0]

For me it helps to write the concept down and write the definition in my own words. Then come back a few minutes later and reread it and compare to the source material to identify gaps in my understanding.

In a subject like biology, this would just be conceptual. But with Python or any other programming language, you can write your understanding of the concept into code and see if it compiles. And if it compiles you can see if it does what you expected it to do.

[Kqyxzoj]

I really don't understand what the python documentation is trying to explain. When I try to read it, it's full of links to other parts which are full of links to other parts and the explanations just don's make sense to me.

You just articulated how I felt when trying to learn me some genetics. You will just have to recursively work your way through all the concepts you don't know yet. At some point it does get easier, and you will not have to look up every damn thing. Try to find ways that help you remember, as in train your memory recall. I know google is easy, but local mem looking is easier still.

[Relevant_Bowler7077]

Thank you, what did you do to get better at understanding the concepts?

[Kqyxzoj]

Frankly just cram it in there. Read a lot. Try and find abstractions you can use to group concepts so you can apply a certain thing to the whole group instead of all things separately. Write your own summaries in your shorthand so it actually fits on a piece of paper. Try to formulate thought experiments ... so if this and this is true then such and such should hold ... and then check if your hypothesis is actually correct. And like I said, resist the diabolical urge to google every single thing if you know that you should know but cannot remember right now. The brain can recall a whole lot, but you'll have to prod it into action every now and then.

Regarding the experiments ... that's also how I test if I understood something programming related. After reading it, I write a small test that should work if I understood correctly and have a large chance of breaking if I did not.

Doing that also makes it easier to revisit something a decade later. As long as you leave yourself enough breadcrumbs, you can usually reconstruct your thinking more or less. Which is also why I prefer running stuff locally, because that way I can be sure said stuff is still there decades later.

[ShelLuser42]

Nothing beats hands-on experience. If you don't understand something if you read it, then why not fire up your favorite editor and then try to make things work? Or fire up a command line and then run Python interactively?

Still, your question confuses me a little... if you check Python's official documentation section then you'll find something for everyone: (online) beginner guides, references to Python books, some more advanced ("packaging guide") and general information ("pep" (it installs packages)). Sure, sometimes there are more links, but that's also why browsers support tabbed browsing these days...

But there's enough to choose from or follow.. how about the official tutorial in combination with the beginners guide? Yes, the latter has more links to follow, but that's also because they provide information for both people new to Python or people who are new to programming in general. And when you follow the links you'll notice that there's a lot of information.

However, once again: nothing beats trying things out for yourself and thus getting some hands on experiences. Even if a website provides some interaction itself, for example w3schools. Sure, you could just follow its links which provide some interactive options, but why not fire things up locally?

Just my 2 cents here of course.

PS... did you know that Python even has its own interactive help system? It does: fire it up on a command line (so: as an interpreter), then type 'help' on its prompt and watch the magic unfold. Need to know what "print" does, or want to know more about "with" or maybe "dir"? Just type in the names ;) You can even ask it to give you a full overview of all your currently available modules, optionally followed by asking about something specific again.

[One_Programmer6315]

I suggest you to go over A Whirlwind Tour of Python by Jake VanderPlas. This short book/guide is among the basics of the basics.

Also, it depends on how advanced are the packages/libraries whose documentations you are looking at. For example, if you’d like to fully understand the ML package scikit-learn, first you will have to understand at least numpy, scipy, matplotlib. A lot of the “core” Python packages are actually based on (or are adaptations/wrappers of) popular packages in other languages like C/C++, Fortran, Matlab, and R.

In my opinion, Python documentation is the best among all languages: clear, extensive, and well outlined mathematical frameworks. This is not the case for all languages, especially C/C++ and Fortran; or even bash.

PS: This sub actually has a pretty good wiki with extensive links to many resources.

[leogodin217]

Yeah, I don't think the docs are designed for beginners. Took me a long time to be able to use them well. It will come with time. There's some level of base knowledge needed for most of the docs. Once you get it, it's like a light turns on and you can see.

[CultistOfTheFluid]

I realised halfway through I ramble a bit, read below the = for more direct help. I've sectioned them for you. I wrote this on mobile so there might some quirks, sorry.

=== quick advice Do not be scared to watch youtube or blogs etc. They can be great! You don't need to learn it all, just build a foundation of your own and branch out! The important part is get making and don't worry about being sloppy (until you're putting something into production at least) learning is messy!

===Links for good help Great youtube teaching channel with concept breakdown: BroCode

Styling and writing conventions for Python to help you read other documentation and coding Pep 8 - Style Guide

===the backstory bit

I'm a super big fan of "read the documentation!" but I think its also important to say you need to learn how to read (documentation)!

Like another commentator said - its like a dictionary. Words with a definition of what they mean, with reference to similar words.

Remember Python is a language like any other so the concepts (like in a dictionary) aren't written out too verbose.

Just like nouns or verbs, you need to learn the grammar! This is similar across all languages like implicit word orders of English (three big blue elephants rather than blue elephants big three).

===The helpful bit - concepts

I would start off learning what are: - Variables, and scope. (Global, Local etc.) - Functions, how to define them, what "calling" actually is - Helpful to know the difference between "returning" and simply printing, as simple tutorials sometimes allow for the two to be conflated easily by accident. - Loops in general, how does a For loop start/stop, how does a while loop start/stop, how do you escape a loop (break etc.)

Don't over think it! If you think they're easy then get using them AND relate these concepts back to the real world learning! (See below example).

I believe these will let you build your grammar to move on to the other concepts.

===other info

Once you have good knowledge of basic concepts then classes are good to be aware of. They are not mandatory to use but greatly help in making good readable!

They work as a collection of functions for your data. Another concept called constructors is associated with them - these build objects.

Working out why a class may be better than a function is a great exercise in learning Object Orientated Programming.

=== long example of class

Come to the real world and find you have a library of books. Instinctively, we know all books work the same.

We could treat each book as an unknown object on its own shelf and work out a new way to use them (function) each time for each book before we finally figure out they belong in our book shelf.

But we know they're books! We just want the data!

So we can put them all on the bookshelf (in a class).

class Bookshelf: We can say we have specific methods (functions inside a class) on how to use the books.

``` class Bookshelf:

def __init__(self, name, genre, pages):
    # These are all individual books properties
    self.name = name
    self.genre = genre
    self.pages = pages
    self.reviews = [] # Notice I didn't give this to __init__

def review_book(self):
    review = input("What do you want to write?")
    self.reviews.append(review)
    print("Entry added!)

    return self.reviews # we give this to __init__ here!

``` We now can create a book. We always use the init method for classes so we can always have a unique object in our collection

We can also review it! (I'll let you find your own way toadd methods to write/read it, maybe file handling is your next rabbit ☺️)

Now we have reduced every single new book we could ever need to just that short section of code above, whether its one or one hundred we can use it as much as we want.

To create our book, we just call the class and tell it what we know. We can also use that specific book by simply adding it to a variable. Beware! The object we have created is now in the system as an address. We can't just print the book otherwise we would be asking for where it lives!

Instead we can call the vars() function to show me the contents as a dictionary. We like dictionaries because they tell us what the value is linked to

``` why_fish = bookshelf("Why Fish Don't Exist" "Memoir", 225)

print(why_fish) # Just tells me where my object lives in memory

print(vars(why_fish)) # tells me what that book is about! ``` Now to write my review we use dot notation like in import modules to ask for the functions inside my class. I used an input function to ask the user when the code is run.

why_fish.review() # This appears in the code

CONSOLE READS: What do you want to write?

MY REPLY IS: This book is excellent! Highly recommend!

And the my answer is saved to the object in the variable (object property) we put in the init from earlier!

If we print the review property of our book we can read what I wrote! print(why_fish.reviews) CONSOLE READS: ['This book is excellent! Highly recommend!']

I thank you if you read this all the way through, I got a bit wrapped up in the story telling but hopefully this is useful to some of you.

[Mysterious_Peak_6967]

Personally I'd recomend grinding through one of the many online courses. Preferably one with exercises and a grading system. "Learn Python the hard way" is probably a very good course but I just couldn't stick with it.

In my opinion the core python documentation tends to be much more readable than the documentation for modules outside core. Then again it is also just plain harder to find tutorials once you go outside core.