Alfred-Workflow

A Python helper library for Alfred 2 Workflow authors, developed and hosted on GitHub.

Alfred Workflows typically take user input, fetch data from the Web or elsewhere, filter them and display results to the user. Alfred-Workflow helps you do these things.

There are convenience methods for:

  • Parsing script arguments.
  • Text decoding/normalisation.
  • Storing data and settings.
  • Caching data from, e.g., web services with a simple API for updating expired data.
  • Securely storing (and syncing) passwords using OS X Keychain.
  • Generating XML output for Alfred.
  • Including external libraries (adding directories to sys.path).
  • Filtering results using an Alfred-like, fuzzy search algorithm.
  • Generating log output for debugging.
  • Running background processes to keep your workflow responsive.
  • Capturing errors, so the workflow doesn’t fail silently.

Quick example

Here’s how to show recent Pinboard.in posts in Alfred.

Create a new Workflow in Alfred’s preferences. Add a Script Filter with Language /usr/bin/python and paste the following into the Script field (changing API_KEY):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import sys
from workflow import Workflow, ICON_WEB, web

API_KEY = 'your-pinboard-api-key'

def main(wf):
    url = 'https://api.pinboard.in/v1/posts/recent'
    params = dict(auth_token=API_KEY, count=20, format='json')
    r = web.get(url, params)
    r.raise_for_status()
    for post in r.json()['posts']:
        wf.add_item(post['description'], post['href'], arg=post['href'],
                    uid=post['hash'], valid=True, icon=ICON_WEB)
    wf.send_feedback()


if __name__ == u"__main__":
    wf = Workflow()
    sys.exit(wf.run(main))

Add an Open URL action to your Workflow with {query} as the URL, connect your Script Filter to it, and you can now hit ENTER on a Pinboard item in Alfred to open it in your browser.

Installation

With pip

You can install Alfred-Workflow directly into your workflow with:

pip install --target=/path/to/my/workflow Alfred-Workflow

Important

If you intend to distribute your workflow to other users, you should include Alfred-Workflow (and other Python libraries your workflow requires) within your workflow as described. Do not ask users to install anything into their system Python.

From source

Download the alfred-workflow-X.X.zip file from the GitHub releases page and either extract the ZIP to the root directory of your workflow (where info.plist is) or place the ZIP in the root directory and add sys.path.insert(0, 'alfred-workflow-X.X.zip') to the top of your Python scripts.

Important

background will not work if you are :importing Alfred-Workflow from a zip file.

If you need to use background, you must extract the zip archive.

Alternatively, you can download the source code from the GitHub repository and copy the workflow subfolder to the root directory of your Workflow.

Your Workflow directory should look something like this (where yourscript.py contains your Workflow code and info.plist is the Workflow information file generated by Alfred):

Your Workflow/
    info.plist
    icon.png
    workflow/
        __init__.py
        background.py
        workflow.py
        web.py
    yourscript.py
    etc.

Or like this:

Your Workflow/
    info.plist
    icon.png
    workflow-1.X.X.zip
    yourscript.py
    etc.

The Alfred-Workflow Tutorial

There is a two-part tutorial on writing an Alfred Workflow with Alfred-Python, taking you through the basics to a full-featured Workflow.

Detailed Reference

API documentation

Detailed documetation of the Alfred-Workflow APIs.

Script Filter results and the XML format

A detailed look at the many parameters accepted by Workflow.add_item() and how they interact with one another.

This should also serve as a decent reference to Alfred’s XML format for folks who aren’t using Alfred-Workflow.

Indices and tables