idiomatic way to extend paths

[wbolster]

it seems hyperlink does not have a nice way to add path components to a base url, which is a very common operation when interacting with rest apis.

for example, consider

>>> from hyperlink import URL
>>> base_url = URL.from_text('https://example.org/api/v2')

let's assume i want to build a url for an endpoint below this base url, e.g. users/search.

this works:

>>> base_url.replace(path=base_url.path + ('users', 'search'))
URL.from_text('https://example.org/api/v2/users/search')

... but let's face it, this is not so nice:

• users/search (likely copied from some documentation) needs manual splitting into a tuple
• base_url is referenced twice since the .path tuple is required for the concatenation

making this nicer is not really possible with the current api. for example:

>>> base_url.replace(path=base_url.path + 'users/search'.split('/'))
[...]
TypeError: can only concatenate tuple (not "list") to tuple

oops. well, that's easy to work around:

>>> base_url.replace(path=base_url.path + tuple('users/search'.split('/')))
URL.from_text('https://example.org/api/v2/users/search')

...but the end result is even uglier.

it would be great if a use case like this is handled with a nicer api. thoughts?

[mahmoud]

I think the idiomatic way is with URL.child(). I guess it's a bit hard to discover, but does that help?

[wbolster]

ah yes, that helps, thanks!

no way to add multiple components using a slash separated string in one go?

.child(*"foo/bar".split())

is, ehm, fugly. ;)

[mahmoud]

I could see automatically splitting the argument(s) by slash and basically doing what you've done there internally. The old URL would allow those special characters through so I'm sure some people used the API that way.

[wbolster]

¿

.child("foo/bar", split=True)

?

[mahmoud]

Finally checked on this, older versions of URL have always escaped slashes, so something like a split kwarg would be necessary for backwards compat. Right now I'm thinking I might be able to subsume this into the solution for #44.