Internet radio browser GUI for music/video streams from various directory services.

⌈⌋ ⎇ branch:  streamtuner2


Update of "plugin meta data"

Overview

Artifact ID: f375b827c8459e7d810f53a25dc7243573323970
Page Name:plugin meta data
Date: 2015-04-03 18:58:11
Original User: mario
Mimetype:text/x-markdown
Parent: b77fb8ba5db39e91ed38fae5c3831c11ad863953 (diff)
Next c713100d9a4b328fbbee3d7c00ed51f5aa8dec0a
Content

Plugin meta spec

Streamtuner2 now uses a proper plugin description scheme. Note that this is completely unrelated to the streamtuner2 or channels API, or how plugins are actually initialized (pkgutil, imp, implib, pluginbase/plugnplay).

Basically the top-level comment block is scanned on initialization. It simply lists a few key: values for documentation and technical descriptors. It's basically a subset of YAML embedded in a script comment.

# api: streamtuner2
# type: feature
# title: My Plugin
# description: Lists all the things
# version: 1.0
# category: music
# config: { name: myconf, value: 1, type: boolean, description: enable foo }
#
# And here goes a longer doc/comment.

The key names are case-insensitive of course. A few fields like title:, description: are required. Theoretically also the api: and type:. But they're only used for decorative purposes like the category: or version: field.

More interestingly the config: field can be used to describe plugin options. Default values will automatically end up in streamtuners conf.* dict, and are presented to users in the config dialog.

  • A value: represents the default.
  • The type: select can be used for dropdown boxes, with a select: key=VAl|key2=VAL2.. attribute for options.
  • Other type: values are interpreted as strings, except type: boolean which becomes a checkbox.
  • A per-option category: attribute is ignored at the moment.
  • Params can be optionally quoted as in `value: "Desc, desc, desc." if they contain commas (which otherwise separate option attrs.)

And of course, the config: field can list multiple options. Simply make it multi-line (every plugin meta field can be) by indenting wrapped lines.

Why?

This scheme is designed to be language-agnostic. It originated in PHP way back (see libconfig), precisely to avoid common misdesigns.

  • Meta data does not belong in code.
    Because that incurs importing them, even when they may go uninitialized/unused.
  • And it certainly should not reside in externalized ini/json data stores.
    Because that's how you get ants!

The meta description block also can double as packaging format. The pack: descriptor is used by fpm/xpm -s src. Which avoids manually concocting separated setup.py/.cfg as the current Python packaging eco system does. (This is stuff which can be automated, without requiring meta information to be doubled in-code and dutifully dished up for pip/setuptools).