Wox Plugin Python
This package provides type definitions for developing Wox plugins in Python.
Requirements
- Python >= 3.8 (defined in
pyproject.toml) - Python 3.12 recommended for development (defined in
.python-version)
Installation
# Using pip
pip install wox-plugin
# Using uv (recommended)
uv add wox-plugin
Usage
This example returns QueryResponse, so the plugin's plugin.json should set
MinWoxVersion to 2.0.4 or newer. Return list[Result] directly if you need
the same plugin build to run on older Wox releases.
from wox_plugin import Query, QueryResponse, Result, Context, PluginInitParams, WoxImage
class MyPlugin:
async def init(self, ctx: Context, params: PluginInitParams) -> None:
self.api = params.API
async def query(self, ctx: Context, query: Query) -> QueryResponse:
# Your plugin logic here
results = []
results.append(
Result(
title="Hello Wox",
sub_title="This is a sample result",
icon=WoxImage.new_emoji("🔍"),
score=100
)
)
return QueryResponse(results=results)
# MUST HAVE! The plugin class will be automatically loaded by Wox
plugin = MyPlugin()
Returning list[Result] directly is deprecated. The Python host still accepts
it for compatibility with older Wox releases. Use QueryResponse only when
plugin.json declares MinWoxVersion >= 2.0.4 so results, refinements, and
layout hints are carried together.
When a plugin needs to control the preview width or grid layout, set
QueryResponse.layout.result_preview_width_ratio or
QueryResponse.layout.grid_layout. The older resultPreviewWidthRatio and
gridLayout metadata features are deprecated because they can only describe
static plugin or command defaults.
Saving Settings
set_setting() requires Wox >= 2.4.0 and accepts a SetSettingOption. Set
is_local=True when a value must stay on the current device and remain outside
Cloud Sync. The older save_setting() method remains available for plugins
targeting Wox releases before 2.4.0, but is deprecated for new integrations.
Query Requirements
Plugins can declare settings that must be configured before Wox calls query():
{
"QueryRequirements": {
"AnyQuery": [
{
"SettingKey": "apiKey",
"Validators": [{ "Type": "not_empty" }],
"Message": "i18n:my_plugin_api_key_required"
}
],
"QueryWithoutCommand": [],
"QueryWithCommand": {
"download": [
{
"SettingKey": "downloadPath",
"Validators": [{ "Type": "not_empty" }]
}
]
}
}
}
License
MIT
Static HTML preview
Use WoxPreviewType.WEBVIEW with a JSON-encoded html field. No HTTP server or temporary HTML file is needed; there is no separate html preview type.
import json
from wox_plugin import WoxPreview, WoxPreviewType
preview = WoxPreview(
preview_type=WoxPreviewType.WEBVIEW,
preview_data=json.dumps({
"html": '<!doctype html><html><body><h1 style="color:teal">Hello Wox</h1></body></html>'
}),
)
# Assign preview to Result(preview=preview, ...).
Set either html or url. Optional JSON fields are injectCss, userAgent, cacheDisabled, and cacheKey (defaults to the URL or HTML). Inline HTML has no plugin-relative base URL: embed CSS/images or use absolute resource URLs. This is browser content, not sanitized Markdown; use html.escape for untrusted text before interpolation.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file wox_plugin-0.0.83.tar.gz.
File metadata
- Download URL: wox_plugin-0.0.83.tar.gz
- Upload date:
- Size: 78.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.0.1 CPython/3.10.20
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fcc2d0b99d5a5404134a6cb373b9aaa89cbed281654b8c4c6f6b1d108667ea68
|
|
| MD5 |
f88ea3ac882e38483f8f03dc9e265f39
|
|
| BLAKE2b-256 |
26237b13e6bee13a4a3dcf31f066fc0deaf2eaeaee45e6a8b3dc23b8667b44c9
|
File details
Details for the file wox_plugin-0.0.83-py3-none-any.whl.
File metadata
- Download URL: wox_plugin-0.0.83-py3-none-any.whl
- Upload date:
- Size: 58.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.0.1 CPython/3.10.20
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
263e01a51cd1290f48560962cf5848d2831dc64df3cd5fd40403dea1a1629715
|
|
| MD5 |
89a42928d683d1faa905225307de2d27
|
|
| BLAKE2b-256 |
153df317c51df318dc3c5d1bfe37bf0215c48651939926bb96335fcd38a644db
|
