gh-82151: Improve docs for urllib3.parse

[idomic]

• Issue: urllib.parse docstrings incomplete #82151

[idomic]

Tagging @taleinat

[taleinat]

The fix here is good and important.

However, this does not address the central issue brought up in bpo-37970, regarding this line of the docs being misleading, since the parts of the netloc are available as additional attributes on the returned named-tuple object:

The components are not broken up in smaller parts (for example, the network location is a single string)

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[idomic]

The fix here is good and important.

However, this does not address the central issue brought up in bpo-37970, regarding this line of the docs being misleading, since the parts of the netloc are available as additional attributes on the returned named-tuple object:

The components are not broken up in smaller parts (for example, the network location is a single string)

You're right, don't know why I missed this part, fixed for both urlsplit and parse.

[idomic]

I have made the requested changes; please review again

[bedevere-bot]

Thanks for making the requested changes!

@taleinat: please review the changes made to this pull request.

[taleinat]

I think this change to the documentation is still not clear enough. Writing "The components are broken up into smaller parts (for example, ...)" is confusing, since for example the query is not broken down into its parts.

What really happens is that the parts as described in the beginning are used as-is for the named-tuple fields. Additionally, only the netloc is broken down into username, password, hostname, and port, and those are added as additional attributes on the returned object. Further, these extra attributes are only accessible by name, but not by index - they are not technically part of the named-tuple's fields.

We need to convey this clearly and concisely, which needs some more thought. The currently suggested wording doesn't achieve this.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[idomic]

@taleinat I've changed one description, once we'll decide on the format I'll clone for the other function

[idomic]

@taleinat ping on that

[taleinat]

Apologies for the delay, @idomic.

What you've written is better, I like the direction :)

I suggest omitting the first sentence, which I find redundant, changing the order of the sentences, and changing "expanded" to "decoded":

The delimiters as shown above
are not part of the result, except for a leading slash in the path component, which is
retained if present.

Additionally, the netloc item is broken down into: username, password, hostname, and port. These are added as additional attributes of the returned object.

% escapes are not decoded.

For example: ...

What do you think?

[idomic]

@taleinat Agree, I like the decoded change, and the first paragraph.
What do you think about:

Additionally, the netloc property is broken down into these additional attributes in the returned object: username, password, hostname, and port.

[idomic]

@taleinat Added the urlsplit() let me know what you think

[taleinat]

Two small comments.

Also, please make sure to wrap the lines at 80 characters, in keeping with (the style guide)[https://devguide.python.org/documenting/#style-guide].

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[idomic]

I have made the requested changes; please review again

[bedevere-bot]

Thanks for making the requested changes!

@taleinat: please review the changes made to this pull request.

[tuukkamustonen]

Looking into this years old PR.

The function docstrings were adjusted in #16458. What remains are updates to the reference docs (this PR).

As I see it, the author has done all the fixes requested.

Added a few comments/suggestions. But in general, it looks good to me.

Maybe @zware @taleinat @encukou could have a look? @idomic you still around to potentiall adjust?

(Looking into this as part of EuroPython 2024 sprint - I'm just a user, not maintainer, fyi.)

[willingc]

Let's reboot this PR and move into a mergeable state.

Suggested changes were applied.