Repository files navigation

A helper library in Python for authors of workflows forAlfred 3 and 4.

Supports Alfred 3 and Alfred 4 on macOS 10.7+ (Python 2.7).

Alfred-Workflow takes the grunt work out of writing a workflow by giving you the tools to create a fast and featureful Alfred workflow from an API, application or library in minutes.

Always supports all current Alfred features.

• Auto-saved settings API for your workflow
• Super-simple data caching with expiry
• Fuzzy filtering (with smart diacritic folding)
• Keychain support for secure storage of passwords, API keys etc.
• Lightweight web API withRequests-like interface
• Background tasks to keep your workflow responsive
• Simple generation of Alfred JSON feedback
• Full support of Alfred's AppleScript/JXA API
• Catches and logs workflow errors for easier development and support
• "Magic" arguments to help development/debugging
• Unicode support
• Pre-configured logging
• Automatically check for workflow updates via GitHub releases
• Post notifications via Notification Center

• Advanced modifiers
• Alfred 4-only updates (won't break older Alfred installs)

• Installation
  • With pip
  • From source
• Usage
  • Workflow script skeleton
  • Examples
    • Web
    • Keychain access
• Documentation
  • Dash docset
• Licensing, thanks
• Contributing
  • Adding a workflow to the list
  • Bug reports, pull requests
  • Contributors
• Workflows using Alfred-Workflow

Note: If you're new to Alfred workflows, check outthe tutorial in the docs.

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

# from your workflow directorypip install --target=. Alfred-Workflow

You can install any other library available on theCheese Shop the same way. See thepip documentation for more information.

It is highly advisable to bundle all your workflow's dependencies with your workflow in this way. That way, it will "just work".

1. Download thealfred-workflow-X.X.X.zip from theGitHub releases page.
2. Extract the ZIP archive and place theworkflow directory in the root folder of your workflow (whereinfo.plist is).

Your workflow should look something like this:

Your Workflow/    info.plist    icon.png    workflow/        __init__.py        background.py        notify.py        Notify.tgz        update.py        version        web.py        workflow.py    yourscript.py    etc.

Alternatively, you can clone/download the Alfred-Workflowrepository and copy theworkflow subdirectory to your workflow's root directory.

A few examples of how to use Alfred-Workflow.

Set up your workflow scripts as follows (if you wish to use the built-in error handling orsys.path modification):

#!/usr/bin/python# encoding: utf-8importsys# Workflow3 supports Alfred 3's new features. The `Workflow` class# is also compatible with Alfred 2.fromworkflowimportWorkflow3defmain(wf):# The Workflow3 instance will be passed to the function# you call from `Workflow3.run`.# Not super useful, as the `wf` object created in# the `if __name__ ...` clause below is global...## Your imports go here if you want to catch import errors, which# is not a bad idea, or if the modules/packages are in a directory# added via `Workflow3(libraries=...)`importsomemoduleimportanothermodule# Get args from Workflow3, already in normalized Unicode.# This is also necessary for "magic" arguments to work.args=wf.args# Do stuff here ...# Add an item to Alfred feedbackwf.add_item(u'Item title',u'Item subtitle')# Send output to Alfred. You can only call this once.# Well, you *can* call it multiple times, but subsequent calls# are ignored (otherwise the JSON sent to Alfred would be invalid).wf.send_feedback()if__name__=='__main__':# Create a global `Workflow3` objectwf=Workflow3()# Call your entry function via `Workflow3.run()` to enable its# helper functions, like exception catching, ARGV normalization,# magic arguments etc.sys.exit(wf.run(main))

Cache data for 30 seconds:

defget_web_data():returnweb.get('http://www.example.com').json()defmain(wf):# Save data from `get_web_data` for 30 seconds under# the key ``example``data=wf.cached_data('example',get_web_data,max_age=30)fordatumindata:wf.add_item(datum['title'],datum['author'])wf.send_feedback()

Grab data from a JSON web API:

data=web.get('http://www.example.com/api/1/stuff').json()

Post a form:

r=web.post('http://www.example.com/',data={'artist':'Tom Jones','song':"It's not unusual"})

Upload a file:

files= {'fieldname' : {'filename':"It's not unusual.mp3",'content':open("It's not unusual.mp3",'rb').read()}}r=web.post('http://www.example.com/upload/',files=files)

WARNING: As this module is based on Python 2's standard HTTP libraries,on old versions of OS X/Python, it does not validate SSL certificates when making HTTPS connections. If your workflow uses sensitive passwords/API keys, you shouldstrongly consider using therequests library upon which theweb.py API is based.

Save password:

wf=Workflow()wf.save_password('name of account','password1lolz')

Retrieve password:

wf=Workflow()wf.get_password('name of account')

The full documentation, including API docs and a tutorial, can be found atdeanishe.net.

The documentation is also available as aDash docset.

The code and the documentation are released under the MIT andCreative Commons Attribution-NonCommercial licences respectively. SeeLICENCE.txt for details.

The documentation was generated usingSphinx and a modified version of theAlabaster theme bybitprophet.

Many of the cooler ideas in Alfred-Workflow were inspired byAlfred2-Ruby-Template by Zhaocai.

The Keychain parser was based onPython-Keyring by Jason R. Coombs.

If you want to add a workflow to thelist of workflows using Alfred-Workflow,don't add it to the docs! The list is machine-generated fromPackal.org and thelibrary_workflows.tsv file. If your workflow is available onPackal, it will be added on the next update. If not, please add it tolibrary_workflows.tsv, and submit a corresponding pull request.

The list is not auto-updated, so if you've released a workflow and are keen to see it in this list, pleaseopen an issue asking me to update the list.

Please seethe documentation.

• Dean Jackson
• Stephen Margheim
• Fabio Niephaus
• Owen Min

Here is a list of some of the many workflows based on Alfred-Workflow.