alpyki - Alfred Python Kit

alpyki helps you create Alfred workflows in Python. It started as a personal extension of pyfred

It comes with a CLI that helps bootstrapping, maintaining and packaging the workflow.

Dependencies are vendored and packaged with the workflow so that they don't need to be installed into the system Python. See the section on adding dependencies for details.

Installation

You can install directly from PyPI:

pip install alpyki

Using the CLI

The CLI knows four commands: new, link, package, vendor.

See alpyki {new,vendor,link,package} -h for detailed help.

New

Bootstraps a new workflow with a single script filter and links it into Alfred.

It creates a new directory with the given name and copies a "Hello Alfred" workflow there. The workflow can be used immediately by invoking Alfred with the specified keyword.

The following example creates a hello directory containing a workflow that can be triggered with the hi keyword. The result of the selected action is copied to the clipboard.

alpyki new hello -k hi -b de.muffix.helloalfred --author=Muffix --description="Hello Alfred"

By default, a GitHub Actions workflow for releases is included. Use --actions gitea to generate a Gitea Actions workflow instead, --actions gitlab for GitLab CI, or --actions none to omit CI files entirely. The --ci flag is an alias for --actions.

Link

Executed from a directory bootstrapped by this CLI, it links or relinks the workflow into Alfred.

alpyki link

Vendor

Downloads the dependencies listed in the requirements.txt file and vendors them into the Workflow/vendored directory. Doing this avoids having to install them into the system Python interpreter.

alpyki vendor

Package

Packages the workflow into a *.alfredworkflow file in the dist directory. The file contains the entire workflow and all dependencies. It can be distributed and imported.

alpyki package

Debug output

The CLI will log debug output if the --debug flag is passed before the command.

Creating a workflow

The classes from the alpyki.model module represent the output expected by Alfred from a script filter.

alpyki.workflow provides a decorator for the entry point of a filter. It preprocesses the input and serialises the response to stdout, where it is being picked up by the next input.

A minimal example for a script filter workflow looks like this:

from alpyki.model import Environment, OutputItem, ScriptFilterOutput
from alpyki.workflow import script_filter

@script_filter
def main(script_path: Path, args_from_alfred: list[str], env: Optional[Environment]) -> ScriptFilterOutput:
    return ScriptFilterOutput(items=[OutputItem(title="Hello Alfred!")])

Adding dependencies

When running the workflow, Alfred will use the system Python interpreter to run the script. Third-party libraries are not available in the interpreter unless explicitly installed. In order to not pollute the system Python, dependencies can be vendored with the workflow using the alpyki vendor command. It is also automatically run with alpyki package.

If you add dependencies to your requirements.txt file, you need to run alpyki vendor to download them. You do not need to prefix the import with vendored because the template adds that directory to the PYTHONPATH variable when the workflow runs.

IDE setup

If you're using an IDE like PyCharm, you'll want to open the generated directory and set up the Workflow subdirectory as the content root. Additionally, you should add the Workflow/vendored directory as source directory in the PyCharm project settings. This helps it resolve the imports correctly.

Adding icons

You can add an icon for your workflow to the Workflow directory in the generated skeleton. The file name must be icon.png

You can assign individual icons to your output items. See the alpyki.model.Icon class for more details.

Distribution through CI releases

The skeleton created by alpyki new comes with a CI action that creates a draft release whenever a tag starting with v is pushed. To create a tag, run git tag v1.0.0 and push it with git push origin v1.0.0. When the action has finished, go to the Releases page of your repository and publish the new release.

By default, a GitHub Actions workflow is generated. Use alpyki new ... --actions gitea to generate a Gitea Actions workflow, --actions gitlab for GitLab CI, or --actions none to skip CI files. The --ci flag is an alias for --actions.