Overview¶

Workflow setup and skeleton¶

Alfred-Python 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:

python yourscript.py "{query}"

where yourscript.py is the name of your script.

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
36
37

#!/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, so all module
    # functions can access it without having to pass the Workflow
    # instance around
    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')

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 replace the workflow if a newer version is available.

Users may turn off automatic checks for updates using the workflow:noautoupdate magic argument.

Currently, only updates from GitHub releases are supported.

For your workflow to be able to recognise and download newer versions, the version value you pass to Workflow should be one of the versions (i.e. tags) in the corresponding GitHub repo’s releases list. See Version numbers for more information.

There must be one (and only one) .alfredworkflow binary attached to a release otherwise it will be ignored. This is the file that will be downloaded and installed via Alfred’s default installation mechanism.

To use this feature, you must pass a dict as the update_settings argument to Workflow. It must have the key/value pair github_slug, which is your username and the name of the workflow’s repo in the format username/reponame. The version of the currently installed workflow must also be specified. You can do this in the update_settings dict or in a version file in the root of your workflow (next to info.plist), e.g.:

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

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:
    wf.start_update()

Or alternatively, create a version file in the root directory or your workflow alongside info.plist:

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

The version file should be plain text with no file extension and contain nothing but the version string, e.g.:

1.2.5

Using a version file:

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

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:
    wf.start_update()

Please see Versioning and migration for detailed information on the required version number format and associated features.

To view update status/install a newer version, the user must either call one of your workflow’s Script Filters with the workflow:update magic argument, in which case Alfred-Workflow will handle the update automatically, or you must add your own update action using Workflow.update_available and Workflow.start_update() to check for and install newer versions respectively.

The check_update() method is called automatically when you create a workflow.workflow.Workflow object. If sufficient time has elapsed since the last check (1 day by default), it starts a background process that checks for new releases. You can alter the update interval with the optional frequency key in update_settings dict (see the example above).

Workflow.update_available is True if an update is available, and False otherwise.

Workflow.start_update() returns False if no update is available, or if one is, it will return True, download the newer version and tell Alfred to install it.

If you want more control over the update mechanism, you can use update.check_update() directly. It caches information on the latest available release under the cache key __workflow_update_status, which you can access via Workflow.cached_data().

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

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

#!/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 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
5

# encoding: utf-8
from __future__ import unicode_literals

ustr = 'This is a Unicode string'
bstr = b'This is an 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

Passes arguments through to XMLGenerator method add_item().

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

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

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.

See workflow.search.filter() for detailed documentation.

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 base.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:	PersistentDict 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:	PersistentDict 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.

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