Overview¶

Supported OS X versions¶

Alfred 2 supports every version of OS X from 10.6 (Snow Leopard). Alfred-Workflow also supports the same versions, but there are a couple of things you have to watch out for because 10.6 has Python 2.6, while later versions have Python 2.7. As a result, if you want to maximise the compatibility of your workflow, you need to avoid using 2.7-only features in your code.

Here is the full list of new features in Python 2.7, but the most important things if you want your workflow to run on Snow Leopard are:

• argparse is not available in 2.6. Use getopt or include argparse in your workflow. Personally, I’m a big fan of docopt for parsing command-line arguments, but argparse is better for certain use cases.
• No dictionary views in 2.6.
• No set literals.
• No dictionary or set comprehensions.
• You must specify field numbers for str.format(), i.e. '{0}.{1}'.format(first, second) not just '{}.{}'.format(first, second).
• No Counter or OrderedDict in collections.

Python 2.6 is still included in later versions of OS X (up to and including Yosemite), so run your Python scripts with /usr/bin/python2.6 in addition to /usr/bin/python (2.7) to make sure they will run on Snow Leopard.

Workflow setup and skeleton¶

Alfred-Workflow is aimed particularly at authors of so-called Script Filters. These are activated by a keyword in Alfred, receive user input and return results to Alfred.

To write a Script Filter with Alfred-Workflow, make sure your Script Filter is set to use /bin/bash as the Language, and select the following (and only the following) Escaping options:

• Backquotes
• Double Quotes
• Dollars
• Backslashes

The Script field should contain the following:

/usr/bin/python yourscript.py "{query}"

where yourscript.py is the name of your script [1].

Your workflow should start out like this. This enables Workflow to capture any errors thrown by your scripts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

import sys

from workflow import Workflow

log = None


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
    import somemodule
    import anothermodule

    # Get args from Workflow as normalized Unicode
    args = wf.args

    # Do stuff here ...

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

    # Send output to Alfred
    wf.send_feedback()


if __name__ == '__main__':
    wf = Workflow()
    # Assign Workflow logger to a global variable for convenience
    log = wf.logger
    sys.exit(wf.run(main))

Including 3rd party libraries¶

It’s a Very Bad Idea ™ to install (or ask users to install) 3rd-party libraries in the OS X system Python. Alfred-Workflow makes it easy to include them in your Workflow.

Simply create a lib subdirectory under your Workflow’s root directory and install your dependencies there. You can call the directory whatever you want, but in the following explanation, I’ll assume you used lib.

To install libraries in your dependencies directory, use:

pip install --target=path/to/my/workflow/lib python-lib-name

The path you pass as the --target argument should be the path to the directory under your Workflow’s root directory in which you want to install your libraries. python-lib-name should be the “pip name” (i.e. the name the library has on PyPI) of the library you want to install, e.g. requests or feedparser.

This name is usually, but not always, the same as the name you use with import.

For example, to install Alfred-Workflow, you would run pip install Alfred-Workflow but use import workflow to import it.

An example: You’re in a shell in Terminal.app in the Workflow’s root directory and you’re using lib as the directory for your Python libraries. You want to install requests. You would run:

pip install --target=lib requests

This will install the requests library into the lib subdirectory of the current working directory.

Then you instantiate Workflow with the libraries argument:

1
2
3
4
5
6
7
8

from workflow import Workflow

def main(wf):
    import requests  # Imported from ./lib

if __name__ == '__main__':
    wf = Workflow(libraries=['./lib'])
    sys.exit(wf.run(main))

When using this feature you do not need to create an __init__.py file in the lib subdirectory. Workflow(…, libraries=['./lib']) and creating ./lib/__init__.py are effectively equal alternatives.

Instead of using Workflow(…, libraries=['./lib']), you can add an empty __init__.py file to your lib subdirectory and import the libraries installed therein using:

from lib import requests

instead of simply:

import requests

Persistent data¶

Alfred provides special data and cache directories for each Workflow (in ~/Library/Application Support and ~/Library/Caches respectively). Workflow provides the following attributes/methods to make it easier to access these directories:

• datadir — The full path to your Workflow’s data directory.
• cachedir — The full path to your Workflow’s cache directory.
• datafile(filename) — The full path to filename under the data directory.
• cachefile(filename) — The full path to filename under the cache directory.

The cache directory may be deleted during system maintenance, and is thus only suitable for temporary data or data that is easily recreated. Workflow‘s cache methods reflect this, and make it easy to replace cached data that are too old. See Caching data for details of the data caching API.

The data directory is intended for more permanent, user-generated data, or data that cannot be otherwise easily recreated. See Storing data for details of the data storage API.

It is easy to specify a custom file format for your stored data via the serializer argument if you want your data to be readable by the user or by other software. See Serialization of stored/cached data for more details.

In addition, Workflow also provides a convenient interface for storing persistent settings with Workflow.settings. See Settings and Keychain access for more information on storing settings and sensitive data.

1
2
3
4
5
6
7

from workflow import web, Workflow

def get_data():
    return web.get('https://example.com/api/stuff').json()

wf = Workflow()
data = wf.cached_data('stuff', get_data, max_age=600)

data = wf.cached_data('stuff', max_age=600)

1
2
3
4

def myfilter(filename):
    return filename.endswith('.zip')

wf.clear_cache(myfilter)

1

wf.clear_cache(lambda f: f.endswith('.zip'))

1
2
3
4
5
6

from workflow import Workflow

wf = Workflow()
wf.store_data('name', data)
# data will be `None` if there is nothing stored under `name`
data = wf.stored_data('name')

1
2
3

wf = Workflow()
wf.settings['key'] = {'key2': 'value'}  # will be automatically saved
wf.settings['key']['key2'] = 'value2'  # will *not* be automatically saved

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from workflow import Workflow

wf = Workflow()

wf.save_password('hotmail-password', 'password1lolz')

password = wf.get_password('hotmail-password')

wf.delete_password('hotmail-password')

# raises PasswordNotFound exception
password = wf.get_password('hotmail-password')

1
2
3
4
5

from workflow.workflow import uninterruptible

@uninterruptible
def critical_function():
     # Your critical code here

Searching/filtering data¶

Workflow.filter() provides an Alfred-like search algorithm for filtering your workflow’s data. By default, Workflow.filter() will try to match your search query via CamelCase, substring, initials and all characters, applying different weightings to the various kind of matches (see Workflow.filter() for a detailed description of the algorithm and match flags).

Best practice is to do the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

def main(wf):

    query = None  # Ensure `query` is initialised

    # Set `query` if a value was passed (it may be an empty string)
    if len(wf.args):
        query = wf.args[0]

    items = load_my_items_from_somewhere()  # Load data from blah

    if query:  # Only call `filter()` if there's a `query`
        items = wf.filter(query, items)

    # Show error if there are no results. Otherwise, Alfred will show
    # its fallback searches (i.e. "Search Google for 'XYZ'")
    if not items:
        wf.add_item('No items', icon=ICON_WARNING)

    # Generate list of results. If `items` is an empty list,
    # nothing will happen
    for item in items:
        wf.add_item(item['title'], ...)

    wf.send_feedback()  # Send results to Alfred via STDOUT

This is by no means essential (wf.args[0] will always be set if the script is called from Alfred via python thescript.py "{query}"), but it won’t work from the command line unless called with an empty string (python thescript.py ""), and it’s good to be aware of when you’re dealing with unset/empty variables.

To use Workflow.filter(), pass it a query, a list of items to filter and sort, and if your list contains items other than strings, a key function that generates a string search key for each item:

1
2
3
4
5
6
7

from workflow import Workflow

names = ['Bob Smith', 'Carrie Jones', 'Harry Johnson', 'Sam Butterkeks']

wf = Workflow()

hits = wf.filter('bs', names)

Which returns:

['Bob Smith', 'Sam Butterkeks']

(bs are Bob Smith’s initials and Butterkeks contains both letters in that order.)

If your data are not strings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from workflow import Workflow

books = [
    {'title': 'A damn fine afternoon', 'author': 'Bob Smith'},
    {'title': 'My splendid adventure', 'author': 'Carrie Jones'},
    {'title': 'Bollards and other street treasures', 'author': 'Harry Johnson'},
    {'title': 'The horrors of Tuesdays', 'author': 'Sam Butterkeks'}
]


def key_for_book(book):
    return '{} {}'.format(book['title'], book['author'])

wf = Workflow()

hits = wf.filter('bot', books, key_for_book)

Which returns:

[{'author': 'Harry Johnson', 'title': 'Bollards and other street treasures'},
 {'author': 'Bob Smith', 'title': 'A damn fine afternoon'}]

hits = wf.filter('bot', books, key_for_book, include_score=True)

[({'author': 'Bob Smith', 'title': 'A damn fine afternoon'},
  11.11111111111111,
  64),
 ({'author': 'Harry Johnson', 'title': 'Bollards and other street treasures'},
  3.3333333333333335,
  64),
 ({'author': 'Sam Butterkeks', 'title': 'The horrors of Tuesdays'}, 3.125, 64)]

[({'author': 'Zoltar', 'title': 'Battle of the Planets'}, 98.0, 8),
 ({'author': 'Brienne of Tarth', 'title': 'How to beat up men'}, 90.0, 16)]

hits = wf.filter('bot', books, key_for_book, min_score=20)

1
2
3
4
5

from workflow import Workflow, MATCH_ALL, MATCH_ALLCHARS

# [...]

hits = wf.filter('bot', books, key_for_book, match_on=MATCH_ALL ^ MATCH_ALLCHARS)

1
2
3
4
5

# match only CamelCase and initials
match_on=MATCH_CAPITALS | MATCH_INITIALS

# match everything but all-characters-in-item and substring
match_on=MATCH_ALL ^ MATCH_ALLCHARS ^ MATCH_SUBSTRING

Retrieving data from the web¶

The unit tests in the source repository contain examples of pretty much everything workflow.web can do:

• GET and POST variables
• Retrieve and decode JSON
• Post JSON
• Post forms
• Automatically handle encoding for HTML and XML
• Basic authentication
• File uploads with forms and without forms
• Download large files
• Variable timeouts
• Ignore redirects

See the API documentation for more information.

Background processes¶

Many workflows provide a convenient interface to applications and/or web services.

For performance reasons, it’s common for workflows to cache data locally, but updating this cache typically takes a few seconds, making your workflow unresponsive while an update is occurring, which is very un-Alfred-like.

To avoid such delays, Alfred-Workflow provides the background module to allow you to easily run scripts in the background.

There are two functions, run_in_background() and is_running(), that provide the interface. The processes started are full daemon processes, so you can start real servers as easily as simple scripts.

Here’s an example of a common usage pattern (updating cached data in the background). What we’re doing is:

1. Checking the age of the cached data and running the update script via run_in_background() if the cached data are too old or don’t exist.
2. (Optionally) informing the user that data are being updated.
3. Loading the cached data regardless of age.
4. Displaying the cached data (if any).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

from workflow import Workflow, ICON_INFO
from workflow.background import run_in_background, is_running

def main(wf):
    # Is cache over 1 hour old or non-existent?
    if not wf.cached_data_fresh('exchange-rates', 3600):
        run_in_background('update',
                          ['/usr/bin/python',
                           wf.workflowfile('update_exchange_rates.py')])

    # Add a notification if the script is running
    if is_running('update'):
        wf.add_item('Updating exchange rates...', icon=ICON_INFO)

    # max_age=0 will load any cached data regardless of age
    exchange_rates = wf.cached_data('exchage-rates', max_age=0)

    # Display (possibly stale) cache data
    if exchange_rates:
        for rate in exchange_rates:
            wf.add_item(rate)

    # Send results to Alfred
    wf.send_feedback()

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

For a working example, see Part 2 of the Tutorial or the source code of my Git Repos workflow, which is a bit smarter about showing the user update information.

Self-updating¶

Add self-updating capabilities to your workflow. It regularly (every day by default) fetches the latest releases from the specified GitHub repository and then asks the user if they want to update the workflow if a newer version is available.

Users can turn off automatic checks for updates with the workflow:noautoupdate magic argument and back on again with workflow:autoupdate.

Currently, only updates from GitHub releases are supported.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from workflow import Workflow

__version__ = '1.1'

...

wf = Workflow(..., update_settings={
    # Your username and the workflow's repo's name
    'github_slug': 'username/reponame',
    # The version (i.e. release/tag) of the installed workflow
    # If a `version` file exists in the root of your workflow,
    # this key may be omitted
    'version': __version__,
    # Optional number of days between checks for updates
    'frequency': 7
}, ...)

...

if wf.update_available:
    # Download new version and tell Alfred to install it
    wf.start_update()

Your Workflow/
    icon.png
    info.plist
    yourscript.py
    version
    workflow/
        ...
        ...

1.2.5

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from workflow import Workflow

...

wf = Workflow(..., update_settings={
    # Your username and the workflow's repo's name
    'github_slug': 'username/reponame',
    # Optional number of days between checks for updates
    'frequency': 7
}, ...)

...

if wf.update_available:
    # Download new version and tell Alfred to install it
    wf.start_update()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

wf = Workflow(...update_settings={...})

if wf.update_available:
    # Add a notification to top of Script Filter results
    wf.add_item('New version available',
                'Action this item to install the update',
                autocomplete='workflow:update',
                icon=ICON_INFO)

# Show other results here
...

Versioning and migration¶

If you intend to distribute your workflow, it’s a good idea to use version numbers. It allows users to see if they’re using an out-of-date version, and more importantly, it allows you to know which version a user has when they ask you for support or to fix a bug (that you may already have fixed).

If your workflow has a version number set (see Setting a version number), the version will be logged every time the workflow is run to help with debugging, and can also be displayed using the workflow:version magic argument.

If you wish to use the self-updating feature, your workflow must have a version number.

Having a version number also enables the first run/migration functionality. See First run/migration below for details.

Your Workflow/
        icon.png
        info.plist
        yourscript.py
        version
        workflow/
                ...

System icons¶

The workflow module provides access to a number of default OS X icons via ICON_* constants for use when generating Alfred feedback:

1
2
3
4
5

from workflow import Workflow, ICON_INFO

wf = Workflow()
wf.add_item('For your information', icon=ICON_INFO)
wf.send_feedback()

List of icons¶

These are all the icons accessible in workflow. They (and more) can be found in /System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/.

Name	Preview
ICON_ACCOUNT
ICON_BURN
ICON_CLOCK
ICON_COLOR
ICON_COLOUR
ICON_EJECT
ICON_ERROR
ICON_FAVORITE
ICON_FAVOURITE
ICON_GROUP
ICON_HELP
ICON_HOME
ICON_INFO
ICON_NETWORK
ICON_NOTE
ICON_SETTINGS
ICON_SWIRL
ICON_SWITCH
ICON_SYNC
ICON_TRASH
ICON_USER
ICON_WARNING
ICON_WEB

If you’d like other standard OS X icons to be added, please add an issue on GitHub.

“Magic” arguments¶

If your Script Filter (or script) accepts a query (or command line arguments), you can pass it so-called magic arguments that instruct Workflow to perform certain actions, such as opening the log file or clearing the cache/settings.

These can be a big help while developing and debugging and especially when debugging problems your Workflow’s users may be having.

The Workflow.run() method (which you should “wrap” your Workflow’s entry functions in) will catch any raised exceptions, log them and display them in Alfred. You can call your Workflow with workflow:openlog as an Alfred query/command line argument and Workflow will open the Workflow’s log file in the default app (usually Console.app).

This makes it easy for you to get at the log file and data and cache directories (hidden away in ~/Library), and for your users to send you their logs for debugging.

Workflow supports the following magic arguments by default:

• workflow:magic — List available magic arguments.
• workflow:help — Open workflow’s help URL in default web browser. This URL is specified in the help_url argument to Workflow.
• workflow:version — Display the installed version of the workflow (if one is set).
• workflow:delcache — Delete the Workflow’s cache.
• workflow:deldata — Delete the Workflow’s saved data.
• workflow:delsettings — Delete the Workflow’s settings file (which contains the data stored using Workflow.settings).
• workflow:foldingdefault — Reset diacritic folding to workflow default
• workflow:foldingoff — Never fold diacritics in search keys
• workflow:foldingon — Force diacritic folding in search keys (e.g. convert ü to ue)
• workflow:opencache — Open the Workflow’s cache directory.
• workflow:opendata — Open the Workflow’s data directory.
• workflow:openlog — Open the Workflow’s log file in the default app.
• workflow:openterm — Open a Terminal window in the Workflow’s root directory.
• workflow:openworkflow — Open the Workflow’s root directory (where info.plist is).
• workflow:reset — Delete the Workflow’s settings, cache and saved data.
• workflow:update — Check for a newer version of the workflow using GitHub releases and install the newer version if one is available.
• workflow:noautoupdate — Turn off automatic checks for updates.
• workflow:autoupdate — Turn automatic checks for updates on.

The three workflow:folding… settings allow users to override the diacritic folding set by a workflow’s author. This may be useful if the author’s choice does not correspond with a user’s usage pattern.

You can turn off magic arguments by passing capture_args=False to Workflow on instantiation, or call the corresponding methods of Workflow directly, perhaps assigning your own keywords within your Workflow:

• open_help()
• open_log()
• open_cachedir()
• open_datadir()
• open_workflowdir()
• open_terminal()
• clear_cache()
• clear_data()
• clear_settings()
• reset() (a shortcut to call the three previous clear_* methods)
• check_update()
• start_update()

wf.magic_prefix = 'wf:'

1
2
3
4
5
6
7
8

wf = Workflow()
wf.magic_prefix = 'wf:'  # Change prefix to `wf:`

def opensettings():
        subprocess.call(['open', wf.settings_path])
        return 'Opening workflow settings...'

wf.magic_arguments['settings'] = opensettings

Serialization of stored/cached data¶

By default, both cache and data files (created using the APIs described in Persistent data) are cached using cPickle. This provides a great compromise in terms of speed and the ability to store arbitrary objects.

When changing or specifying a serializer, use the name under which the serializer is registered with the workflow.manager object.

1
2

wf = Workflow()
wf.cache_serializer = 'pickle'

In the case of stored data, you are free to specify either a global default serializer or one for each individual datastore:

1
2
3
4
5
6

wf = Workflow()
# Use `pickle` as the global default serializer
wf.data_serializer = 'pickle'

# Use the JSON serializer only for these data
wf.store_data('name', data, serializer='json')

This is primarily so you can create files that are human-readable or useable by other software. The generated JSON is formatted to make it readable.

The stored_data() method can automatically determine the serialization of the stored data (based on the file extension, which is the same as the name the serializer is registered under), provided the corresponding serializer is registered. If it isn’t, a ValueError will be raised.

1
2
3
4

# Reading
obj = serializer.load(open('filename', 'rb'))
# Writing
serializer.dump(obj, open('filename', 'wb'))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

 from workflow import Workflow, manager


 class MySerializer(object):

     @classmethod
     def load(cls, file_obj):
         # load data from file_obj

     @classmethod
     def dump(cls, obj, file_obj):
         # serialize obj to file_obj

 manager.register('myformat', MySerializer())

1
2

serializer.load(file_obj)
serializer.dump(obj, file_obj)

Encoded strings and Unicode¶

This is a brief guide to Unicode and encoded strings aimed at Alfred-Workflow users (and Python coders in general) who are unfamiliar with them.

Encoding errors are by far the most common group of bugs in Python workflows in the wild (they’re so easy for developers to miss).

This guide should give you an idea of what Unicode and encoded strings are, and why and how you as a workflow developer should deal with them.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

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

# Because we want to work with Unicode, it's simpler if we make
# literal strings in source code Unicode strings by default, so
# we set `encoding: utf-8` at the very top of the script to tell Python
# that this source file is UTF-8 and import `unicode_literals` before any
# code.
#
# See Tip further down the page for more info

from __future__ import unicode_literals, print_function

import subprocess
from workflow import Workflow

wf = Workflow()
# wf.args decodes and normalizes sys.argv for you
query = wf.args[0]
# `subprocess` returns encoded strings (UTF-8 in this case)
# Note: the arguments are prefixed with `b` because of unicode_literals
# You should pass encoded strings to `subprocess`. It doesn't much
# matter in this case, as everything can be encoded to ASCII, but if you're
# passing in, say, a user-supplied query, be sure to encode it to UTF-8
output = subprocess.check_output([b'mdfind', b'-onlyin',
                                  os.getenv('HOME'),
                                  b'kind:folder date:today'])
# Convert to Unicode and NFC-normalize
output = wf.decode(output)
# Split the output into individual filepaths
paths = [s.strip() for s in output.split('\n') if s.strip()]
# Filter paths by query
paths = wf.filter(query, paths,
                  # We just want to filter on filenames, not the whole path
                  key=lambda s: os.path.basename(s),
                  min_score=30)

if paths:
   # For demonstration purposes, pass the first result as `{query}`
   # to the next workflow Action.
   print(paths[0].encode('utf-8'))

>>> u = u'Fahrvergnügen'  # This is a Unicode string
>>> enc1 = u.encode('utf-8')  # OS X default encoding
>>> enc2 = u.encode('latin-1')  # Older standard German encoding
>>> enc1 == enc2
False
>>> u == enc1
UnicodeWarning: Unicode equal comparison failed to convert both arguments to Unicode - interpreting them as being unequal
False
>>> unicode(enc1, 'utf-8') == unicode(enc2, 'latin-1')
True

1
2
3
4

# encoding: utf-8

ustr = u'This is a Unicode string'
bstr = 'This is a UTF-8 encoded string'

1
2
3
4
5

# encoding: utf-8
from __future__ import unicode_literals

ustr = 'This is a Unicode string'
bstr = b'This is a UTF-8 encoded string'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

>>> from unicodedata import normalize
>>> from glob import glob
>>> name = u'München.txt'  # German for 'Munich'. NFC-normalized, as it's Python source code
>>> print(repr(name))
u'M\xfcnchen.txt'
>>> open(name, 'wb').write('')  # Create an empty text file called `München.txt`

>>> for filename in glob(u'*.txt'):
...     if filename == name:
...         print(u'Match : {0} ({0!r}) == {1} ({1!r})'.format(filename, name))
...     else:
...         print(u'No match : {0} ({0!r}) != {1} ({1!r})'.format(filename, name))
...
# The filename has been NFD-normalized by the filesystem
No match : München.txt (u'Mu\u0308nchen.txt') != München.txt (u'M\xfcnchen.txt')
>>> for filename in glob(u'*.txt'):
...     filename = normalize('NFC', filename)  # Ensure the same normalization
...     if filename == name:
...         print(u'Match : {0} ({0!r}) == {1} ({1!r})'.format(filename, name))
...     else:
...         print(u'No match : {0} ({0!r}) != {1} ({1!r})'.format(filename, name))
...
Match : München.txt (u'M\xfcnchen.txt') == München.txt (u'M\xfcnchen.txt')

The Workflow Object¶

The Workflow object is the main interface to this library.

See Workflow setup and skeleton in the User Manual for an example of how to set up your Python script to best utilise the Workflow object.

class workflow.workflow.Workflow(default_settings=None, update_settings=None, input_encoding=u'utf-8', normalization=u'NFC', capture_args=True, libraries=None, help_url=None)¶

Create new Workflow instance.

Parameters:

default_settings (dict) – default workflow settings. If no settings file exists, Workflow.settings will be pre-populated with default_settings. update_settings (dict) – settings for updating your workflow from GitHub. This must be a dict that contains github_slug and version keys. github_slug is of the form username/repo and version must correspond to the tag of a release. See Self-Updating for more information. input_encoding (unicode) – encoding of command line arguments normalization (unicode) – normalisation to apply to CLI args. See Workflow.decode() for more details. capture_args (Boolean) – capture and act on workflow:* arguments. See Magic arguments for details. libraries (tuple or list) – sequence of paths to directories containing libraries. These paths will be prepended to sys.path. help_url (unicode or str) – URL to webpage where a user can ask for help with the workflow, report bugs, etc. This could be the GitHub repo or a page on AlfredForum.com. If your workflow throws an error, this URL will be displayed in the log and Alfred’s debugger. It can also be opened directly in a web browser with the workflow:help magic argument.

add_item(title, subtitle=u'', modifier_subtitles=None, arg=None, autocomplete=None, valid=False, uid=None, icon=None, icontype=None, type=None, largetext=None, copytext=None)¶

Add an item to be output to Alfred

Parameters:

title (unicode) – Title shown in Alfred subtitle (unicode) – Subtitle shown in Alfred modifier_subtitles (dict) – Subtitles shown when modifier (CMD, OPT etc.) is pressed. Use a dict with the lowercase keys cmd, ctrl, shift, alt and fn arg (unicode) – Argument passed by Alfred as {query} when item is actioned autocomplete (unicode) – Text expanded in Alfred when item is TABbed valid (Boolean) – Whether or not item can be actioned uid (unicode) – Used by Alfred to remember/sort items icon (unicode) – Filename of icon to use icontype (unicode) – Type of icon. Must be one of None , 'filetype' or 'fileicon'. Use 'filetype' when icon is a filetype such as 'public.folder'. Use 'fileicon' when you wish to use the icon of the file specified as icon, e.g. icon='/Applications/Safari.app', icontype='fileicon'. Leave as None if icon points to an actual icon file. type (unicode) – Result type. Currently only 'file' is supported (by Alfred). This will tell Alfred to enable file actions for this item. largetext (unicode) – Text to be displayed in Alfred’s large text box if user presses CMD+L on item. copytext (unicode) – Text to be copied to pasteboard if user presses CMD+C on item.

Returns:

Item instance

See the Script Filter Results and the XML Format section of the documentation for a detailed description of what the various parameters do and how they interact with one another.

See System icons for a list of the supported system icons.

Note

Although this method returns an Item instance, you don’t need to hold onto it or worry about it. All generated Item instances are also collected internally and sent to Alfred when send_feedback() is called.

The generated Item is only returned in case you want to edit it or do something with it other than send it to Alfred.

alfred_env¶

Alfred’s environmental variables minus the alfred_ prefix.

New in version 1.7.

The variables Alfred 2.4+ exports are:

Variable	Description
alfred_preferences	Path to Alfred.alfredpreferences (where your workflows and settings are stored).
alfred_preferences_localhash	Machine-specific preferences are stored in Alfred.alfredpreferences/preferences/local/<hash> (see alfred_preferences above for the path to Alfred.alfredpreferences)
alfred_theme	ID of selected theme
alfred_theme_background	Background colour of selected theme in format rgba(r,g,b,a)
alfred_theme_subtext	Show result subtext. 0 = Always, 1 = Alternative actions only, 2 = Selected result only, 3 = Never
alfred_version	Alfred version number, e.g. '2.4'
alfred_version_build	Alfred build number, e.g. 277
alfred_workflow_bundleid	Bundle ID, e.g. net.deanishe.alfred-mailto
alfred_workflow_cache	Path to workflow’s cache directory
alfred_workflow_data	Path to workflow’s data directory
alfred_workflow_name	Name of current workflow
alfred_workflow_uid	UID of workflow

Note: all values are Unicode strings except version_build and theme_subtext, which are integers.

Returns:	dict of Alfred’s environmental variables without the alfred_ prefix, e.g. preferences, workflow_data.

args¶

Return command line args as normalised unicode.

Args are decoded and normalised via decode().

The encoding and normalisation are the input_encoding and normalization arguments passed to Workflow (UTF-8 and NFC are the defaults).

If Workflow is called with capture_args=True (the default), Workflow will look for certain workflow:* args and, if found, perform the corresponding actions and exit the workflow.

See Magic arguments for details.

bundleid¶

Workflow bundle ID from environmental vars or info.plist.

Returns:	bundle ID
Return type:	unicode

cache_data(name, data)¶

Save data to cache under name.

If data is None, the corresponding cache file will be deleted.

Parameters:	name – name of datastore data – data to store. This may be any object supported by the cache serializer

cache_serializer¶

Name of default cache serializer.

New in version 1.8.

This serializer is used by cache_data() and cached_data()

See SerializerManager for details.

Returns:	serializer name
Return type:	unicode

cached_data(name, data_func=None, max_age=60)¶

Retrieve data from cache or re-generate and re-cache data if stale/non-existant. If max_age is 0, return cached data no matter how old.

Parameters:	name – name of datastore data_func (callable) – function to (re-)generate data. max_age (int) – maximum age of cached data in seconds
Returns:	cached data, return value of data_func or None if data_func is not set

cached_data_age(name)¶

Return age of data cached at name in seconds or 0 if cache doesn’t exist

Parameters:	name (unicode) – name of datastore
Returns:	age of datastore in seconds
Return type:	int

cached_data_fresh(name, max_age)¶

Is data cached at name less than max_age old?

Parameters:	name – name of datastore max_age (int) – maximum age of data in seconds
Returns:	True if data is less than max_age old, else False

cachedir¶

Path to workflow’s cache directory.

The cache directory is a subdirectory of Alfred’s own cache directory in ~/Library/Caches. The full path is:

~/Library/Caches/com.runningwithcrayons.Alfred-2/Workflow Data/<bundle id>

Returns:	full path to workflow’s cache directory
Return type:	unicode

cachefile(filename)¶

Return full path to filename within your workflow’s cache directory.

Parameters:	filename (unicode) – basename of file
Returns:	full path to file within cache directory
Return type:	unicode

check_update(force=False)¶

Call update script if it’s time to check for a new release

New in version 1.9.

The update script will be run in the background, so it won’t interfere in the execution of your workflow.

See Self-updating in the User Manual for detailed information on how to enable your workflow to update itself.

Parameters:	force (Boolean) – Force update check

clear_cache(filter_func=<function <lambda>>)¶

Delete all files in workflow’s cachedir.

Parameters:	filter_func (callable) – Callable to determine whether a file should be deleted or not. filter_func is called with the filename of each file in the data directory. If it returns True, the file will be deleted. By default, all files will be deleted.

clear_data(filter_func=<function <lambda>>)¶

Delete all files in workflow’s datadir.

Parameters:	filter_func (callable) – Callable to determine whether a file should be deleted or not. filter_func is called with the filename of each file in the data directory. If it returns True, the file will be deleted. By default, all files will be deleted.

clear_settings()¶

Delete workflow’s settings_path.

data_serializer¶

Name of default data serializer.

New in version 1.8.

This serializer is used by store_data() and stored_data()

See SerializerManager for details.

Returns:	serializer name
Return type:	unicode

datadir¶

Path to workflow’s data directory.

The data directory is a subdirectory of Alfred’s own data directory in ~/Library/Application Support. The full path is:

~/Library/Application Support/Alfred 2/Workflow Data/<bundle id>

Returns:	full path to workflow data directory
Return type:	unicode

datafile(filename)¶

Return full path to filename within your workflow’s data directory.

Parameters:	filename (unicode) – basename of file
Returns:	full path to file within data directory
Return type:	unicode

decode(text, encoding=None, normalization=None)¶

Return text as normalised unicode.

If encoding and/or normalization is None, the input_encoding``and ``normalization parameters passed to Workflow are used.

Parameters:	text (encoded or Unicode string. If text is already a Unicode string, it will only be normalised.) – string encoding (unicode or None) – The text encoding to use to decode text to Unicode. normalization (unicode or None) – The nomalisation form to apply to text.
Returns:	decoded and normalised unicode

Workflow uses “NFC” normalisation by default. This is the standard for Python and will work well with data from the web (via web or json).

OS X, on the other hand, uses “NFD” normalisation (nearly), so data coming from the system (e.g. via subprocess or os.listdir()/os.path) may not match. You should either normalise this data, too, or change the default normalisation used by Workflow.

delete_password(account, service=None)¶

Delete the password stored at service/account. Raises PasswordNotFound if account is unknown.

Parameters:	account (unicode) – name of the account the password is for, e.g. “Pinboard” service (unicode) – Name of the service. By default, this is the workflow’s bundle ID

dumbify_punctuation(text)¶

Convert non-ASCII punctuation to closest ASCII equivalent.

This method replaces “smart” quotes and n- or m-dashes with their workaday ASCII equivalents. This method is currently not used internally, but exists as a helper method for workflow authors.

Parameters:	text (unicode) – text to convert
Returns:	text with only ASCII punctuation
Return type:	unicode

filter(query, items, key=<function <lambda>>, ascending=False, include_score=False, min_score=0, max_results=0, match_on=127, fold_diacritics=True)¶

Fuzzy search filter. Returns list of items that match query.

query is case-insensitive. Any item that does not contain the entirety of query is rejected.

Warning

If query is an empty string or contains only whitespace, a ValueError will be raised.

Parameters:	query (unicode) – query to test items against items (list or tuple) – iterable of items to test key (callable) – function to get comparison key from items. Must return a unicode string. The default simply returns the item. ascending (Boolean) – set to True to get worst matches first include_score (Boolean) – Useful for debugging the scoring algorithm. If True, results will be a list of tuples (item, score, rule). min_score (int) – If non-zero, ignore results with a score lower than this. max_results (int) – If non-zero, prune results list to this length. match_on (int) – Filter option flags. Bitwise-combined list of MATCH_* constants (see below). fold_diacritics (Boolean) – Convert search keys to ASCII-only characters if query only contains ASCII characters.
Returns:	list of items matching query or list of (item, score, rule) tuples if include_score is True. rule is the MATCH_* rule that matched the item.
Return type:	list

Matching rules

By default, filter() uses all of the following flags (i.e. MATCH_ALL). The tests are always run in the given order:

1. MATCH_STARTSWITH : Item search key startswith

   ``query``(case-insensitive).

2. MATCH_CAPITALS : The list of capital letters in item

   search key starts with query (query may be lower-case). E.g., of would match OmniFocus, gc would match Google Chrome

3. MATCH_ATOM : Search key is split into “atoms” on

   non-word characters (.,-,’ etc.). Matches if query is one of these atoms (case-insensitive).

4. MATCH_INITIALS_STARTSWITH : Initials are the first

   characters of the above-described “atoms” (case-insensitive).

5. MATCH_INITIALS_CONTAIN : query is a substring of

   the above-described initials.

6. MATCH_INITIALS : Combination of (4) and (5).

7. MATCH_SUBSTRING : Match if query is a substring

   of item search key (case-insensitive).

8. MATCH_ALLCHARS : Matches if all characters in

   query appear in item search key in the same order (case-insensitive).

9. MATCH_ALL : Combination of all the above.

MATCH_ALLCHARS is considerably slower than the other tests and provides much less accurate results.

Examples:

To ignore MATCH_ALLCHARS (tends to provide the worst matches and is expensive to run), use match_on=MATCH_ALL ^ MATCH_ALLCHARS.

To match only on capitals, use match_on=MATCH_CAPITALS.

To match only on startswith and substring, use match_on=MATCH_STARTSWITH | MATCH_SUBSTRING.

Diacritic folding

New in version 1.3.

If fold_diacritics is True (the default), and query contains only ASCII characters, non-ASCII characters in search keys will be converted to ASCII equivalents (e.g. ü -> u, ß -> ss, é -> e).

See ASCII_REPLACEMENTS for all replacements.

If query contains non-ASCII characters, search keys will not be altered.

first_run¶

Return True if it’s the first time this version has run.

New in version 1.9.10.

Raises a ValueError if version isn’t set.

fold_to_ascii(text)¶

Convert non-ASCII characters to closest ASCII equivalent.

New in version 1.3.

Note

This only works for a subset of European languages.

Parameters:	text (unicode) – text to convert
Returns:	text containing only ASCII characters
Return type:	unicode

get_password(account, service=None)¶

Retrieve the password saved at service/account. Raise PasswordNotFound exception if password doesn’t exist.

Parameters:	account (unicode) – name of the account the password is for, e.g. “Pinboard” service (unicode) – Name of the service. By default, this is the workflow’s bundle ID
Returns:	account password
Return type:	unicode

info¶

dict of info.plist contents.

item_class¶

alias of Item

last_version_run¶

Return version of last version to run (or None)

New in version 1.9.10.

Returns:	Version instance or None

logfile¶

Return path to logfile

Returns:	path to logfile within workflow’s cache directory
Return type:	unicode

logger¶

Create and return a logger that logs to both console and a log file.

Use open_log() to open the log file in Console.

Returns:	an initialised Logger

magic_arguments = None¶

Mapping of available magic arguments. The built-in magic arguments are registered by default. To add your own magic arguments (or override built-ins), add a key:value pair where the key is what the user should enter (prefixed with magic_prefix) and the value is a callable that will be called when the argument is entered. If you would like to display a message in Alfred, the function should return a unicode string.

By default, the magic arguments documented here are registered.

magic_prefix = None¶

The prefix for all magic arguments. Default is workflow:

name¶

Workflow name from Alfred’s environmental vars or info.plist.

Returns:	workflow name
Return type:	unicode

open_cachedir()¶

Open the workflow’s cachedir in Finder.

open_datadir()¶

Open the workflow’s datadir in Finder.

open_help()¶

Open help_url in default browser

open_log()¶

Open workflows logfile in standard application (usually Console.app).

open_terminal()¶

Open a Terminal window at workflow’s workflowdir.

open_workflowdir()¶

Open the workflow’s workflowdir in Finder.

reset()¶

Delete settings, cache and data

run(func)¶

Call func to run your workflow

Parameters:	func – Callable to call with self (i.e. the Workflow instance) as first argument.

func will be called with Workflow instance as first argument.

func should be the main entry point to your workflow.

Any exceptions raised will be logged and an error message will be output to Alfred.

save_password(account, password, service=None)¶

Save account credentials.

If the account exists, the old password will first be deleted (Keychain throws an error otherwise).

If something goes wrong, a KeychainError exception will be raised.

Parameters:	account (unicode) – name of the account the password is for, e.g. “Pinboard” password (unicode) – the password to secure service (unicode) – Name of the service. By default, this is the workflow’s bundle ID

send_feedback()¶

Print stored items to console/Alfred as XML.

set_last_version(version=None)¶

Set last_version_run to current version

New in version 1.9.10.

Parameters:	version (Version instance or unicode) – version to store (default is current version)
Returns:	True if version is saved, else False

settings¶

Return a dictionary subclass that saves itself when changed.

See Settings in the User Manual for more information on how to use settings and important limitations on what it can do.

Returns:	Settings instance initialised from the data in JSON file at settings_path or if that doesn’t exist, with the default_settings dict passed to Workflow on instantiation.
Return type:	Settings instance

settings_path¶

Path to settings file within workflow’s data directory.

Returns:	path to settings.json file
Return type:	unicode

start_update()¶

Check for update and download and install new workflow file

New in version 1.9.

See Self-updating in the User Manual for detailed information on how to enable your workflow to update itself.

Returns:	True if an update is available and will be installed, else False

store_data(name, data, serializer=None)¶

Save data to data directory.

New in version 1.8.

If data is None, the datastore will be deleted.

Note that the datastore does NOT support mutliple threads.

Parameters:	name – name of datastore data – object(s) to store. Note: some serializers can only handled certain types of data. serializer – name of serializer to use. If no serializer is specified, the default will be used. See SerializerManager for more information.
Returns:	data in datastore or None

stored_data(name)¶

Retrieve data from data directory. Returns None if there are no data stored.

New in version 1.8.

Parameters:	name – name of datastore

update_available¶

Is an update available?

New in version 1.9.

See Self-updating in the User Manual for detailed information on how to enable your workflow to update itself.

Returns:	True if an update is available, else False

version¶

Return the version of the workflow

New in version 1.9.10.

Get the version from the update_settings dict passed on instantiation or the version file located in the workflow’s root directory. Return None if neither exist or ValueError if the version number is invalid (i.e. not semantic).

Returns:	Version of the workflow (not Alfred-Workflow)
Return type:	Version object

workflowdir¶

Path to workflow’s root directory (where info.plist is).

Returns:	full path to workflow root directory
Return type:	unicode

workflowfile(filename)¶

Return full path to filename in workflow’s root dir (where info.plist is).

Parameters:	filename (unicode) – basename of file
Returns:	full path to file within data directory
Return type:	unicode