URI Netloc deprecated; replaced by Authority

[codingpathfinder]

Documentation

cpython has several references to "netloc" (primarily in the Lib and urllib libraries). This term describes the network location and login information in a URI (Uniform Resource Indicator) as seen in RFC 1808, but has been outdated since 1998 and 2005 with the publishing of RFC 2396 and RFC 3986 which is the Internet Standard. The correct term for this URI component is "authority."

This excerpt from RFC 3986 shows the components of the URI:

   The following are two example URIs and their component parts:

         foo://example.com:8042/over/there?name=ferret#nose
         \_/   \______________/\_________/ \_________/ \__/
          |           |            |            |        |
       scheme     authority       path        query   fragment
          |   _____________________|__
         / \ /                        \
         urn:example:animal:ferret:nose

This update would require renaming all references of "netloc" and "net_loc" to "authority" or some abbreviation (E.g. "auth"). Because this would be a breaking change, it perhaps is not a documentation update. However, the other issue types didn't seem to fit. Thanks.

Linked PRs

• GH-115577 Clarify netloc term usage in urllib.parse docs #117632
• [3.12] GH-115577 Clarify netloc term usage in urllib.parse docs (GH-117632) #118656

[gpshead]

FYI - The Python URL code/APIs/docs originated from prior to RFC 2396. We aren't going to deprecate the netloc name being used in any APIs such as https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlparse as that would be a needlessly breaking change.

The lowest hanging fruit for this is indeed just mention the terminology equivalence in relevant places in our documentation.

Code wise, if someone really wanted to, adding an alternate name for those who want to refer to it as an attribute or keyword argument using the perhaps more modern authority name rather than .netloc or netloc= is plausible. That is mostly a matter of using a @property on classes and some new logic around a keyword only argument on callables. It'd need documenting, and the implementation needs to ensure that an error is raised if both are passed when it is a function argument. I'm not sure it is worthwhile, allowing both forms could just add confusion.

I'd start with just a documentation update.

[codingpathfinder]

@gpshead this makes sense. Agreed a documentation update is probably the best next step. Also, thanks @AlexWaygood for the renaming the title appropriately.

[Privat33r-dev]

@AlexWaygood can you assign me? I plan to do it in 1-3 days.

[AlexWaygood]

@Privat33r-dev, feel free to work on issues without being assigned :) We don't usually require somebody to be assigned in order for them to start working on an issue; we'll happily accept PRs from anybody if they're of sufficient quality.

(Also, please refrain from pinging core devs unless you know they have an interest or expertise in an issue. I know next-to-nothing about this area -- my only involvement here so far has been to fix a typo in the issue title :)

[Privat33r-dev]

(Also, please refrain from pinging core devs unless you know they have an interest or expertise in an issue. I know next-to-nothing about this area -- my only involvement here so far has been to fix a typo in the issue title :)

You are listed as an expert in the Documentation, that's why I thought that it would be appropriate :)

I remember that I saw somewhere that you should respond to the issue to ask to assign you with timeframe if you want to work on something, it was somewhere in the devguide, I guess. Currently I was unable to find it.

But good to know current practices, thanks.

[Privat33r-dev]

Found that place unintentionally:
https://devguide.python.org/documentation/help-documenting/#helping-with-documentation-issues

leave a comment on the issue saying you are going to try and create a pull request and roughly how long you think you will take to do so (this allows others to take on the issue if you happen to forget or lose interest).

Sorry, still couldn't find a time to do this.