{"id":29197429,"url":"https://github.com/flow-launcher/flow.launcher.plugin.pythontemplate","last_synced_at":"2025-07-02T07:09:06.698Z","repository":{"id":44846143,"uuid":"262525462","full_name":"Flow-Launcher/Flow.Launcher.Plugin.PythonTemplate","owner":"Flow-Launcher","description":"A python language template for building Flow Launcher plugin","archived":false,"fork":false,"pushed_at":"2021-08-17T22:40:30.000Z","size":90,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-01T11:26:56.031Z","etag":null,"topics":["flow","flow-launcher","python","python-template","template","template-advice"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Flow-Launcher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-09T08:31:11.000Z","updated_at":"2023-11-22T16:52:04.000Z","dependencies_parsed_at":"2022-08-12T11:40:14.777Z","dependency_job_id":null,"html_url":"https://github.com/Flow-Launcher/Flow.Launcher.Plugin.PythonTemplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Flow-Launcher/Flow.Launcher.Plugin.PythonTemplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flow-Launcher%2FFlow.Launcher.Plugin.PythonTemplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flow-Launcher%2FFlow.Launcher.Plugin.PythonTemplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flow-Launcher%2FFlow.Launcher.Plugin.PythonTemplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flow-Launcher%2FFlow.Launcher.Plugin.PythonTemplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Flow-Launcher","download_url":"https://codeload.github.com/Flow-Launcher/Flow.Launcher.Plugin.PythonTemplate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Flow-Launcher%2FFlow.Launcher.Plugin.PythonTemplate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263091080,"owners_count":23412358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flow","flow-launcher","python","python-template","template","template-advice"],"created_at":"2025-07-02T07:09:00.491Z","updated_at":"2025-07-02T07:09:06.683Z","avatar_url":"https://github.com/Flow-Launcher.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Template for Flow Plugin\n\nThis is a framework template for developing Flow Launcher plugins in Python.\n\nIt logically breaks the code down into components and also includes tools to\ngenerate plugin information, test locally, and to allow for langauge localisation.\n\nIt is not mandatory to use this template,\nhowever doing so helps standardize Python plugins and may assist in debugging.\n\n## :bookmark: Versions\n\n- [Flow](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.PythonTemplate/tree/master)\n- [Wox](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.PythonTemplate/tree/wox)\n\n## :pushpin: Requirements\n\n- [`flowlauncher`](https://github.com/Flow-Launcher/Flow.Launcher.JsonRPC.Python) Flow's jsonRPC API for Python. It's **NECESSARY** for plugin.\n- `python-dotenv` User's config package.\n\n## :file_folder: File Structure\n\n```\n.\n│  README.md\n│  LICENSE\n│  plugin.json\n│  .gitignore\n│  .env\n│  main.py\n│  test.py\n|  commands.py\n│  requirements.txt\n|  requirements-dev.txt\n|  babel.cfg\n│\n├─assets\n│      example.png\n│      favicon.ico\n│\n└─plugin  # main scripts\n        __init__.py\n        extensions.py\n        settings.py\n        templates.py\n        ui.py\n        utils.py\n        └──translations  # localization\n                ├─en_US\n                └─zh_CN\n```\n\nThe following is some more detail on the important files.\n\n### :snake: Script File\n\n#### main.py\n\nThe Python entry point to your plugin (depend on `plugin.json`).\n\nYou **shouldn't** have to edit this file.\n\n#### test.py\n\nA file that calls the Flowlauncher query via `main.py` and displays\nthe results on the command line so you can **debug**.\n\nThis file is for developing and doesn't need to be packaged with the plugin.\n\n#### extensions.py\n\nThere is a example to show how to use the **3rd package**.\n\nCurrently used for `localization` and shouldn't need to be edited unless\nyou change where the localization files are stored.\n\n#### settings.py\n\nEdit this file to add in information for your plugin that is used throughout the code.\n\nAlso uses `dotenv` to load the `.env` file for localization.\n\n#### templates.py\n\nComes with templates for the JSON RPC query result and action.\n\nOther templates can be added here as you need them.\n\n#### ui.py\n\nThe interaction with the Flow Launcher JSON RPC happens here.\n\nThe `query` function will have your main query logic.\n\nMost of your code and development will happen in this file and `utils.py`.\n\n#### utils.py\n\n`ui.py` should only hold the UI logic to keep the main thought simple.\n\n`utils.py` could finish other function.\n\n#### :computer: commands.py\n\nThis template uses `click` to parse the command line arguments for\nthe different functions that `commands.py` can perform.\n\n##### gen-plugin-info\n\nUsing Example:\n\n```python\npython commands.py gen-plugin-info\n```\n\nWe can use the `commands.py` to update `plugin.json` using\nthe variables from the package itself.\n\nThese are imported from `settings.py` in the **plugin** folder.\n\n##### :globe_with_meridians: Localization Commands\n\nThe next few functions allow you to use localization to translate strings\nin your plugin to different languages.\n\nYou are not required to cater for more than one language but\nFlow Launcher is used around the world and many users appreciate being able to\nuse it in their own language.\n\nIf you need help translating to a language, try posting a request on the [Discord](https://discord.gg/AvgAQgh).\n\n###### init\n\nUsing Example:\n\n```python\npython commands.py init lang\n```\n\nUsing `gettext` in your code you can integrate localization functionality.\n\nThe [gettext documentation](https://docs.python.org/3/library/gettext.html#internationalizing-your-programs-and-modules)\nhelps explain this but essentially you wrap any string with\nthe default gettext tag (underscore and brackets) and\nthe functions below will know to extract these out to be translated.\n\nFor example:\n\nRegular string\n\n```python\nself.sendNormalMess(f\"Error - {my_err_string}\", \"Check documentation for accepted units\")\n```\n\nAdding `gettext` tags to be able to translate both strings\n\n```python\nself.sendNormalMess(_(f\"Error - {my_err_string}\"), _(\"Check documentation for accepted units\"))\n```\n\nWe can initialize a language (en, zh, es, etc.) using the init function.\n\nThis uses `babel.cfg` to know where and which files to search for the `gettext` strings.\n\nThis will add these strings to a special text file `messages.po` for each language\nin the **translations** folder.\n\nYou can then edit this file to add in the specific string translations for that specific language.\n\n###### update\n\nUsing Example:\n\n```python\npython commands.py update\n```\n\nWhen you update your code, use this function to update the localization strings.\n\n###### compile\n\nUsing Example:\n\n```python\npython commands.py compile\n```\n\nBefore shipping the plugin, we need to compile the `.po` file to a `.mo` file for\neach langauge with the compile function.\n\n### :package: Package File\n\n#### requirements.txt\n\nThe Python package requirements for your plugin.\n\nCurrently the user needs to manually install these\nonce they have installed the plugin as Flow does no Python package management.\n\nThe easiest way to do this is for the user to run.\n\nUsing Example:\n\n```powershell\npip install -r requirements.txt\n```\n\n#### plugin.json\n\nThe file that Flow uses to incorporate your plugin to the plugin manifest list.\n\nSee [commands.py](#computer-commandspy).\n\n### :wrench: Config File\n\n#### .env\n\nThe user config file.\n\nYou could change another name sound good for the **User**.\n\nCurrently sets the language for the plugin.\n\nThe user will need to manually edit this once the plugin is installed to change the language.\n\nIf you have localized the plugin,please see [commands.py](#computer-commandspy).\n\n#### babel.cfg\n\nBabel config file showing where to look for strings that can be translated.\n\n### :globe_with_meridians: Localization\n\nThese are your localization folders for each langauge your plugin supports.\n\n`plugin\\translations\\[LANGUAGE]\\LC_MESSAGES`\n\nThe template comes with English (US) and Chinese but\nyou can add as many as you would like to support.\n\nThe `po` and the `mo` files are described above.\n\n## :runner: ToDos\n\n- [x] auto commands\n- [x] local language\n- [ ] inputs parser, for multiple inputs\n- [ ] setting ui for Flow\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflow-launcher%2Fflow.launcher.plugin.pythontemplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflow-launcher%2Fflow.launcher.plugin.pythontemplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflow-launcher%2Fflow.launcher.plugin.pythontemplate/lists"}