DecodedURL.to_uri is inconsistent with DecodedURL.normalize, .child, etc

[glyph]

I was pretty surprised to discover just now that DecodedURL.to_uri returns a URL object, rather than a DecodedURL. Given that almost all the other methods wrap the passed-through object, why does this one not?

I'm not sure how we get out of the compatibility jam if we decide this is wrong, but it seems wrong to me.

[mahmoud]

Yeah the wrapped surface area is not the clearest. to_uri, to_iri, and to_text are all passthroughs. to_text makes immediate sense to keep as a passthrough, and it's the one I use most. I'm less sure about the other two.

I'm curious, what were you planning on doing with the URL once you got it? The docstring of to_uri says

This is useful to do in preparation for sending a :class:URL over a network protocol.

But why one wouldn't go straight to to_text is less clear to me.

[wsanchez]

But why one wouldn't go straight to to_text is less clear to me.

Perhaps that's an argument to deprecate to_uri (and to_iri) altogether?

It would obliquely dodge the compatibility jam by removing the API instead of changing it in a way that's hard to reconcile.

[glyph]

@mahmoud to_text converts your URI to text, for reading by a human (or embedding in a web page or a tweet or whatever), in its exact current form.

to_uri converts your URL to an ascii-only representation, which can be used to synthesize the bytes required for an HTTP request, or for storage in a system which is going to make HTTP requests with a client that may not be as sophisticated as a browser, or as Hyperlink itself, or for anywhere you need something non-unicode-aware.

It converts to a URL object rather than text or bytes directly because you still might want to manipulate it in that state, or to inspect its differences.

I like what @wsanchez is saying here though, in the sense that we should probably have better names for these. At the time, neck-deep in protocol specifications, asURI() was the intuitively obvious choice here, but in the harsh light of the following day's second system syndrome, it's clear that this nomenclature is obscure.

I am struggling to come up with something even marginally succinct, and I hate these names, but just as a starting point for discussion: as_ascii_only_for_machines and as_readable_text_for_humans ?

[glyph]

I'm curious, what were you planning on doing with the URL once you got it? The docstring of to_uri says

This is useful to do in preparation for sending a :class:URL over a network protocol.

But why one wouldn't go straight to to_text is less clear to me.

It's true that I think this is a low-urgency issue precisely because 99.9% of uses of to_uri will be followed by an immediate to_text. (But that also implies that maybe we can get away with a compatibility exception.)

[mahmoud]

Interesting. Well, my first instinct is to add an as_ascii or ascii flag to to_text and then talk about the use cases in the docs a bit. 2c, etc.

[wsanchez]

I was going to suggest as_text and as_ascii for @glyph's long names.

[wsanchez]

And still deprecate as_uri. You can get the EncodedURL back out if you need that, but it seems we think you probably don't.

[mahmoud]

I like that, too.

[glyph]

Just wanted to point out that we should not have both "as_text" and "to_text" :). And we need more than a text-based manipulation here, the thing the methods do (give you a URL) is useful.

This is an interesting bikeshed, though. Another possible color: .asciify() / .readable() ?

[glyph]

Or ... .internationalize() ?

[glyph]

.for_display() / .for_wire()

[glyph]

Apparently the RFC calls them .ToASCII() and .ToUnicode() and maybe we should just follow suit: https://tools.ietf.org/html/rfc3490#section-4.1

[glyph]

(okay okay I'm actually done for now)

[twm]

The RFC names make more sense than the status quo to me