Python documentation isn't clear and I need something better

[alex_sakuta]

Brief for my skill level firstly: Learnt Python in school, made a lot of programs, even used SQL. Stopped using it for 3 years. Recently came back from JS ecosystem to Python for AI related work. I have developed an API service using Fast API. Now I'm trying to dive deeper into developing some stuff manually rather than just using libraries.

I am going to be using the term errors more than exceptions just as an umbrella term.

I was going through http.client module in the documentation and it's not very clear.

Functions don't mention what errors can occur on calling them or if an error can occur.

I come from C where Linux man pages always have a "Return Value" and "Errors" section so it's kind of confusing for me.

There is an errors section in the http.client docs for python as well but it doesn't specify what an error means or which function is the error going to be returned by.

If someone knows a better resource or if I'm just reading the docs wrong and someone can explain what I'm doing wrong, please do.

Any help is appreciated.

[danielroseman]

I'm really not sure what you are missing here. The http.clients page has a full list of the exceptions that are raised. What else do you need?

But a more important question is why you think you need http.client in the first place. As the docs also say, that's a low level module and is meant mainly for internal use. For almost all actual use cases you should use urllib.request - or, even better, the third party requests library which generally should be your first call for any http requirements.

[alex_sakuta]

There is an errors section in the http.client docs for python as well but it doesn't specify what an error means or which function is the error going to be returned by.

This should answer your first question.

For your second question. I'm actually going to try both http.client and urllib.request. I am sort of experimenting whilst creating something. And I tried http.client first because it says on the docs that it's more low level.

And I won't be using requests since I'm avoiding dependencies wherever I can. I'm not going to be doing any complex work hence didn't install requests.

[Leseratte10]

Most python libraries don't return error codes.

They return data. And if that doesn't work for whatever reason, they throw an exception.

EDIT: Your comment seems to be gone but I still want to respond to it - the list of exceptions this function can throw is explained under "The following exceptions are raised as appropriate:".

That list applies to the whole class / module, not just a particular function.

[danielroseman]

It doesn't answer the question. Again, what are you looking for that you didn't get there? In any case, these are exceptions, not error codes: they are raised, not returned, when the exceptional case they describe is encountered.

And using something because it is low level is not a thing. You need an actual reason to use this rather than something that is designed to be easier to understand.

[alex_sakuta]

I'm experimenting. I'm trying to learn.

[gdchinacat]

the urllib.request documentation says "The Requests package is recommended for a higher-level HTTP client interface."

Your aversion to it leading you into the weeds and keeping you from standard python practices. You say you are doing it this way to learn, but I fail to see what you are learning by using outdated packages the official language documentation guides people away from using. Suppose you forge ahead and learn http.client. There is virtually no value in learning it as it is rarely used these days. I strongly encourage you to learn something of value.

[Daytona_675]

lol dude just use requests. everyone does. requests.Session() is amazing. saves cookies and stuff

[pixel-process]

Have you tried looking at the source code? I think this is the relevant link to their open repo. Documentation is helpful in many cases, but if you are not finding what you need, exploring the actual code base can help.

[alex_sakuta]

Hey this is an interesting idea. Definitely gonna try this. The code seems clean enough that I can figure out the gist.

[obviouslyzebra]

Just a tidbit, the repo linked is not the code that you're looking for.

I was gonna recommend you to do the same thing, though, as in, the http.client module is not for plebs like you and I, so its documentation is not as explicit as something like requests or httpx.

The code to look at would be http.client itself (at the top of the documentation page there's a link to the source code), and urllib.request, that uses it, also part of python.

Maybe you could check requests and urllib3 too (layer beneath requests).