A helper library in Python for authors of workflows for Alfred 2.

• Catches and logs workflow errors for easier development and support
• "Magic" arguments to help development/debugging
• Auto-saves settings
• Super-simple data caching
• Fuzzy, Alfred-like search/filtering with diacritic folding
• Keychain support for secure storage of passwords, API keys etc.
• Simple generation of Alfred feedback (XML output)
• Input/output decoding for handling non-ASCII text
• Lightweight web API with Requests-like interface
• Pre-configured logging
• Painlessly add directories to sys.path
• Easily launch background tasks (daemons) to keep your workflow responsive

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

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

Note: 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 ###

1. Download the alfred-workflow-X.X.zip from the releases page.
2. Either extract the ZIP archive and place the workflow directory in the root folder of your workflow (where info.plist is) or
3. Place the ZIP archive in the root folder of your workflow and add sys.path.insert(0, 'alfred-workflow-X.X.zip') at the top of your Python script(s).

Your workflow should look something like this:

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

Or this:

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

Note: the background.py module will not work from within a zip archive.

Alternatively, you can clone/download the Alfred-Workflow repository and copy the workflow 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 or sys.path modification):

#!/usr/bin/python
# encoding: utf-8

import sys

from workflow import Workflow


def main(wf):
    # The Workflow instance will be passed to the function
    # you call from `Workflow.run`
    # Your imports here if you want to catch import errors
    # or if the modules/packages are in a directory added via `Workflow(libraries=...)`
    import somemodule
    import anothermodule
    # Get args from Workflow, already in normalised Unicode
    args = wf.args

    # Do stuff here ...

    # Add an item to Alfred feedback
    wf.add_item(u'Item title', u'Item subtitle')

    # Send output to Alfred
    wf.send_feedback()


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

Cache data for 30 seconds:

def get_web_data():
    return web.get('http://www.example.com').json()

def main(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)
    for datum in data:
        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, it cannot validate SSL certificates when making HTTPS connections. If your workflow uses sensitive passwords/API keys, you should strongly consider using the requests library upon which the web.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 auto-generated API docs and a tutorial, can be found here.

The code and the documentation are released under the MIT and Creative Commons Attribution-NonCommercial licences respectively. See LICENSE for details.

The documentation was generated using Sphinx, Sphinx Bootstrap Theme, Bootstrap and the Readable Bootswatch theme.

• Dean Jackson
• Stephen Margheim

These are some of the Alfred workflows that use this library.

• Alfred Backblaze by XedMada. Pause and Start Backblaze online backups.
• Alfred Dependency Bundler Demo (Python) by deanishe. Demonstration on how to use the Alfred Bundler in Python.
• AppScripts by deanishe. List, search and run/open AppleScripts for the active application.
• BibQuery by hackademic. Search BibDesk from the comfort of your keyboard.
• Blur by Tyler Eich. Set Alfred's background blur radius.
• Convert by deanishe. Convert between different units. No Internet connection required.
• Date Calculator by MuppetGate. A basic date calculator.
• Digital Ocean status by frankspin. Check the status of your Digital Ocean droplets.
• Display Brightness by fniephaus. Adjust your display's brightness with Alfred.
• Dropbox Client for Alfred by fniephaus. Access multiple Dropbox accounts with Alfred.
• Duden Search by deanishe. Search duden.de German dictionary (with auto-suggest).
• Fabric for Alfred by fniephaus. Quickly execute Fabric tasks.
• Fuzzy Folders by deanishe. Fuzzy search across folder subtrees.
• Git Repos by deanishe. Browse, search and open Git repositories from within Alfred.
• Glosbe Translation by deanishe. Translate text using Glosbe.com.
• Homebrew for Alfred by fniephaus. Easily control Homebrew with Alfred.
• IPython Notebooks by nkeim. Search notebook titles on your IPython notebook server.
• Laser SSH by paperElectron. Choose SSH connection from filterable list.
• LibGen by hackademic. Search and Download pdfs and ebooks from Library Genesis.
• Network Location by deanishe. List, filter and activate network locations from within Alfred.
• Packal Workflow Search by deanishe. Search Packal.org from the comfort of Alfred.
• Pandoctor by hackademic. An Alfred GUI for Pandoc.
• Parsers by hackademic. Greek and Latin parsers.
• Pocket for Alfred by fniephaus. Manage your Pocket list with Alfred.
• Quick Stocks by paperElectron. Add some stock symbols for Alfred to check for you.
• Readability for Alfred by fniephaus. Manage your Readability list with Alfred.
• Relative Dates by deanishe. Generate relative dates based on a simple input format.
• SEND by hackademic. Send documents to the cloud.
• Searchio! by deanishe. Auto-suggest search results from multiple search engines and languages.
• Skimmer by hackademic. Actions for PDF viewer Skim.
• Snippets by hackademic. Simple, document-specific text snippets.
• Spritzr by hackademic. An Alfred Speed-Reader.
• Sublime Text Projects by deanishe. View, filter and open your Sublime Text (2 and 3) project files.
• Torrent by bfw. Search for torrents, choose among the results in Alfred and start the download in uTorrent.
• Travis CI for Alfred by fniephaus. Quickly check build statuses on travis-ci.org.
• VM Control by fniephaus. Control your Parallels and Virtual Box virtual machines.
• Wikify by hackademic. Your little Evernote Wiki-Helper.
• ZotQuery by hackademic. Search Zotero. From the Comfort of Your Keyboard.