Document DecodedURL

[twm]

There don't seem to be API docs for DecodedURL. As far as I can see it's only mentioned in the docstring of hyperlink.parse (which also mentions EncodedURL without explaining that URL is EncodedURL).

URL's escaping behavior is inconsistent between path manipulation functions and querystring manipulators. The former escape, while the latter validate input:

Python 3.7.7 (default, Mar 10 2020, 15:16:38) 
>>> from hyperlink import URL, DecodedURL
>>> u = URL.from_text('https://example.com')
>>> u.child('foo/bar')
URL.from_text('https://example.com/foo%2Fbar')
>>> u.add('foo', '&')
Traceback (most recent call last):
  ...
ValueError: one or more reserved delimiters &# present in query parameter value: '&'

The documentation of add(), set(), etc. should at least mention this validation.

DecodedURL has consistent behavior: both escape as required:

>>> du = DecodedURL.from_text('https://example.com')
>>> du.child('foo/bar')
DecodedURL(url=URL.from_text('https://example.com/foo%2Fbar'))
>>> du.add('foo', '&')
DecodedURL(url=URL.from_text('https://example.com/?foo=%26'))

I find this behavior less surprising.