插件¶

Datasette 的插件系统允许将附加功能实现为 Python 代码（或前端 JavaScript），这些功能可以打包在单独的 Python 包中。底层机制使用 pluggy。

请参阅 Datasette 插件目录获取现有插件列表，或查看 GitHub 上的 datasette-plugin 主题。

您可以使用插件做的事情包括

向 Datasette 添加可视化功能，例如 datasette-cluster-map 和 datasette-vega。
使新的自定义 SQL 函数可在 Datasette 中使用，例如 datasette-haversine 和 datasette-jellyfish。
使用自定义扩展定义自定义输出格式，例如 datasette-atom 和 datasette-ics。
添加可在 Jinja 自定义模板中调用的模板函数，例如 datasette-render-markdown。
自定义数据库值在 Datasette 界面中的渲染方式，例如 datasette-render-binary 和 datasette-pretty-json。
自定义 Datasette 的认证和权限系统的工作方式，例如 datasette-auth-tokens 和 datasette-permissions-sql。

安装插件¶

如果插件已使用 setuptools 打包分发，您可以通过将其与 Datasette 一起安装在同一虚拟环境或 Docker 容器中使用该插件。

您可以使用 datasette install 命令安装插件

datasette install datasette-vega

您可以使用 datasette uninstall 卸载插件

datasette uninstall datasette-vega

您可以使用 datasette install --upgrade 或 datasette install -U 升级插件

datasette install -U datasette-vega

此命令也可用于将 Datasette 本身升级到最新发布的版本

datasette install -U datasette

这些命令是 pip install 和 pip uninstall 的简单封装，可确保它们在与 Datasette 本身相同的虚拟环境中运行 pip。

使用 --plugins-dir 的一次性插件¶

您还可以通过将一次性项目插件保存为 plugins/ 文件夹中的 plugin_name.py 函数，然后使用 --plugins-dir 选项将该文件夹传递给 datasette 来定义它们

datasette mydb.db --plugins-dir=plugins/

使用 datasette publish 部署插件¶

datasette publish 和 datasette package 命令都接受一个可选的 --install 参数。您可以多次使用此参数来告诉 Datasette 在过程中 pip install 指定的插件

datasette publish cloudrun mydb.db --install=datasette-vega

您可以使用 PyPI 上的包名称或 pip install 的任何其他有效参数，例如 .zip 文件的 URL

datasette publish cloudrun mydb.db \
    --install=https://url-to-my-package.zip

查看已安装的插件¶

您可以通过导航到您的 Datasette 实例的 /-/plugins 页面来查看已安装插件的列表 - 例如：https://fivethirtyeight.datasettes.com/-/plugins

您也可以使用 datasette plugins 命令

$ datasette plugins
[
    {
        "name": "datasette_json_html",
        "static": false,
        "templates": false,
        "version": "0.4.0"
    }
]

如果您运行 datasette plugins --all，它将包含作为 Datasette 一部分提供的默认插件

[
    {
        "name": "datasette.actor_auth_cookie",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "actor_from_request"
        ]
    },
    {
        "name": "datasette.blob_renderer",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "register_output_renderer"
        ]
    },
    {
        "name": "datasette.default_magic_parameters",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "register_magic_parameters"
        ]
    },
    {
        "name": "datasette.default_menu_links",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "menu_links"
        ]
    },
    {
        "name": "datasette.default_permissions",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "permission_allowed"
        ]
    },
    {
        "name": "datasette.facets",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "register_facet_classes"
        ]
    },
    {
        "name": "datasette.filters",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "filters_from_request"
        ]
    },
    {
        "name": "datasette.forbidden",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "forbidden"
        ]
    },
    {
        "name": "datasette.handle_exception",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "handle_exception"
        ]
    },
    {
        "name": "datasette.publish.cloudrun",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "publish_subcommand"
        ]
    },
    {
        "name": "datasette.publish.heroku",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "publish_subcommand"
        ]
    },
    {
        "name": "datasette.sql_functions",
        "static": false,
        "templates": false,
        "version": null,
        "hooks": [
            "prepare_connection"
        ]
    }
]

您可以添加 --plugins-dir= 选项以包含在该目录中找到的任何插件。

插件配置¶

插件可以拥有自己的配置，嵌入在元数据文件中。插件的配置选项位于该文件中的 "plugins" 键下，可以包含在根、数据库或表级别。

这里是针对特定表的一些插件配置示例

{
    "databases": {
        "sf-trees": {
            "tables": {
                "Street_Tree_List": {
                    "plugins": {
                        "datasette-cluster-map": {
                            "latitude_column": "lat",
                            "longitude_column": "lng"
                        }
                    }
                }
            }
        }
    }
}

这会告诉 datasette-cluster-map 插件对于名为 sf-trees.db 的数据库文件中的名为 Street_Tree_List 的表，应使用哪个纬度和经度列。

秘密配置值¶

嵌入在 metadata.json 中的任何值对于查看您的 Datasette 实例的 /-/metadata 页面的任何人都是可见的。某些插件可能需要保密的配置 - 例如 API 密钥。您可以通过两种方式存储秘密配置值。

作为环境变量。如果您的秘密位于 Datasette 进程可访问的环境变量中，您可以像这样指示应从该环境变量读取配置值

{
    "plugins": {
        "datasette-auth-github": {
            "client_secret": {
                "$env": "GITHUB_CLIENT_SECRET"
            }
        }
    }
}

作为单独文件中的值。您的秘密也可以存储在磁盘上的文件中。要指定应从文件读取秘密，请提供完整文件路径，如下所示

{
    "plugins": {
        "datasette-auth-github": {
            "client_secret": {
                "$file": "/secrets/client-secret"
            }
        }
    }
}

如果您使用 datasette publish 系列命令发布数据，您可以使用 --plugin-secret 选项在发布时设置这些秘密。例如，使用 Heroku，您可能会运行以下命令

$ datasette publish heroku my_database.db \
    --name my-heroku-app-demo \
    --install=datasette-auth-github \
    --plugin-secret datasette-auth-github client_id your_client_id \
    --plugin-secret datasette-auth-github client_secret your_client_secret

这将设置必要的环境变量并将以下内容添加到已部署的 metadata.json 中

{
    "plugins": {
        "datasette-auth-github": {
            "client_id": {
                "$env": "DATASETTE_AUTH_GITHUB_CLIENT_ID"
            },
            "client_secret": {
                "$env": "DATASETTE_AUTH_GITHUB_CLIENT_SECRET"
            }
        }
    }
}