Overview

This proposal changes how external plugins are located by PyScript, and how they are installed. For the purposes of this discussion, an 'external plugin' is any plugin that is not built-into the PyScript codebase. (I.e. not py-terminal, py-splashscreen, etc).

This is based on the discussion by @fpliger, @antocuni, @philippjfr, @ntoll, and I on Friday, Feb 24 at the PyScript offsite. See Future Expansion for elements of that conversation that have been left out of this proposal.

Py-Config

This proposal makes a change to the contents of the plugins key in <py-config>. Previously, this was a list of URLs to single files ending in '.js' or '.py'; these resources were fetched and installed as plugins based on their file ending.

Under this proposal, the plugins key would contain a list of URLs pointing to metadata files as specified below. These can be .json or .toml resources; if the URL ends in one of these filetypes, PyScript will try to parse the file as the matching type. If the URL doesn't end in either of these, it is attempted to be parsed as JSON, then as TOML.

Metadata File

A plugin metadata file is a single JSON or TOML file containing all the information needed to describe, fetch resources for, and initialize a plugin.

The description of the keys of the Metadata file are broken into two types for ease of reading: Functional Keys, which have a direct impact on the behavior of the plugin, how it is loaded/referenced/executed/etc.; and Descriptive Keys, which contain additional textual metadata about the plugin. There is no separation of the keys within the Metadata file; the distinction is purely notional.

Functional Keys

Functional Keys contain values which have a direct effect on the loading an operation of the plugin. They comprise the only required keys - name, language, and entrypoint - and additional optional keys which allow plugins to add values to the list of packages to install and fetch configurations to execute.

Descriptive Keys

Descriptive Keys contain values which describe the project, its origin, usage, or documentation. They are available at run time to PyScript, but are not used to drive plugin-related behaviors directly within the app. The fields listed below may be required if the plugin is to be included in a central plugin index; this is left to the specification by the the index creator. Users made include additional descriptive keys to their Metadata file if they wish.

Python Plugin Installation Location

At the offsite, we didn't come to a conclusion as to where exactly the plugin entrypoint file (and any additional files [[fetch]]'d by the plugin) end up in the Virtual Filesystem. We discussed several options - in the root folder, in a separate folder per plugin, in a separate plugins folder, etc. This is an important question which will need to be answered before we can implement this proposal.

To keep this discussion to a reasonable length, those options are enumerated in a separate Discussion #1229.

For Future Expansion

This proposal does not cover all of the things discussed at the offsite that we'd like plugins and the metadata file to be able to do. Specifically:

• Allowing users to specify plugins by name (or URL) from central index, e.g. anacondaPyScriptPlugins:pirateplug or something instead of a fully qualified URL.
• Allowing plugins to 'depend' on each other, and exactly how this would work, both in a "what is the desired resolution behavior/order" sense and a "how is this specified by the plugin" sense.

Example

To illustrate the features of this new architecture, what follows is in the sample metadata file for a Python plugin called noawait, which, at load time, parses all the PyScript tags on the page looking for async/await/asyncio-looking things, and plays a sound if there are any.

The plugin fetches the required sound file using a relative URL. It specifies the entrypoint file to fetch (main.py) as well as some additional Python and binary files to fetch. The plugin uses the packages key to install ffmpeg to adjust the pitch of the sound at runtime. Finally, some descriptive keys are added for context.

Index.html

<py-config>
    plugins = ["https://example.com/resources/noawait.json"]
</py-config>

noawait.json

{
    "name": "noawait",
    "language": "python",
    "entrypoint": "main.py",
    "packages": ["ffmpeg"],
    "fetch": [
        {
            "files": ["main.py"]
        },
        {
            "files": ["sound.py", "parser.py", "wavetable.bin"],
            "from": "utils",
            "to_folder": "utils"
        }
    ],
    "metadataVersion": 1,
    "readableName": "No Await",
    "version": "1.0",
    "description": "This plugin prevents async/await from being used.",
    "author": "Jeff Glass",
    "url": "https://www.example.com/noawait/docs/index.html"
}