smartplaylist: add --uri-format option

[mgoltzsche]

Beets' web API already allows remote players to access audio files but it doesn't provide a way to expose the playlists defined using the smartplaylist plugin.
This PR makes the smartplaylist plugin provides an option to generate ID-based item URIs/URLs instead of paths.
Once playlists are generated this way, they can be served using a regular HTTP server such as nginx or copied to clients/players.

To provide sufficient flexibility for various ways of integrating beets remotely (e.g. beets API, beets API with context path, AURA API, mopidy resource URI, etc), the new option has been defined as a template with an $id placeholder (assuming each remote integration requires a different path schema but they all rely on using the beets item id as identifier/path segment).

To prevent local path-related plugin configuration from leaking into a HTTP URL-based playlist generation (invoked with CLI option in addition to the local playlists generated into another directory), setting the new option makes the plugin ignore the other path-related options prefix, relative_to, forward_slash and urlencode.

Usage examples:

• beet splupdate --uri-format 'http://beets:8337/item/$id/file' (for beets web API)
• beet splupdate --uri-format 'http://beets:8337/aura/tracks/$id/audio' (for AURA API)
• beet splupdate --uri-format 'beets:library:track;$id' (for mopidy-beets)

(While it was already possible to generate playlists containing HTTP URLs previously using the prefix option, it did not allow to generate ID-based URLs pointing to the beets web API but required to expose the audio files using a web server directly and refer to them using their file system $path.)

Depends on:

• smartplaylist: expose config as CLI options #5047

Relates to:

• Expose playlists within web API #5037
• smartplaylist: add extm3u/extinf/m3u8 support #5046
• smartplaylist: change option --extm3u to --output #5053

To Do

• Documentation. (If you've added a new command-line flag, for example, find the appropriate page under docs/ to describe it.)
• Changelog. (Add an entry to docs/changelog.rst to the bottom of one of the lists near the top of the document.)
• Tests. (Very much encouraged but not strictly required.)

[sampsyo]

Looks good overall, and it doesn't seem likely to disrupt other users of this plugin!

Here is one small design-choice: currently, the template uses the literal string $id and a plain old str.replace to fill it in. Would it make sense to future-proof this a little by using proper Python string templates? The placeholder would be {id}, and we'd fill it in like tpl.format(id=...). Maybe that's over-engineering and we never want that level of complexity, but I just thought I'd ask. 😃

[mgoltzsche]

@sampsyo I am fine with making the change you suggested. However, can you please elaborate in which way your suggested change is making it more future-proof.
My thinking to pick the $id placeholder was to provide a UX that is consistent with the path templates within the configuration while at the same time I didn't want to use item.evaluate_template for this purpose yet since it supports a bunch of other placeholders that are not required yet (as far as I can see) but eventually somebody may require them one day and even have the need to add the song title as URL-encoded path segment or so which could be possible using the template functionality that is also used for the file paths. In case such a feature would be required one day, tpl.replace("$id", ...) could be replaced with item.evaluate_template() without breaking compatibility. Your suggested change is fine for the current requirements but as soon as somebody has more complex requirements, she either has to implement it within another new option or break compatibility (in absence of developing another template/expression language on top of the str.format syntax).

[mgoltzsche]

Thinking about consistency, I realize it would be more consistent to call the option --format instead of --uri-template, aligned with the beet ls command's option with the same name.
Correspondingly, the option to enable m3u8 (#5053) should be renamed from --format to --output (or so)...
WDYT?

[mgoltzsche]

I adjusted both PRs correspondingly (--output=m3u|m3u8 and --format=.../$id/... options). Though, corresponding to the ls command's --format option, it is still using $id as placeholder. Do you want me to change that?

[mgoltzsche]

I renamed the option again: it is now called --uri-format to be more specific and leave the door open for consistent CLI evolution to template additional fields in the future, if needed.
Now the PR is really ready for re-review 😅.
Do you still want me to use {id} instead of $id as placeholder, taking the UX consistency into account?

[sampsyo]

I am fine with making the change you suggested. However, can you please elaborate in which way your suggested change is making it more future-proof.

Basically, I just meant that—if we ever want to have more complex formatting going on here than just substituting a single number with no conversion—we might want a more flexible way to specify the format. But you make a good point that, even if we did that, we might still want beets's $foo-style templating instead of Python's {foo}-style templating!

[sampsyo]

This all looks great to me!! I like the new name uri_format; it is a bit more consistent. I'll merge this now!