Skip to content

blizzrdof77/alfred-workflow

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

565 Commits

bin

bin

 
 

docs

docs

 
 

extras

extras

 
 

tests

tests

 
 

workflow

workflow

 
 

.coveragerc

.coveragerc

 
 

.gitignore

.gitignore

 
 

.gitmodules

.gitmodules

 
 

.travis.yml

.travis.yml

 
 

Alfred-Workflow 2.0.ft

Alfred-Workflow 2.0.ft

 
 

LICENCE.txt

LICENCE.txt

 
 

MANIFEST.in

MANIFEST.in

 
 

README.md

README.md

 
 

README_PYPI.rst

README_PYPI.rst

 
 

TODO

TODO

 
 

alfred-workflow-1.32.zip

alfred-workflow-1.32.zip

 
 

icon.png

icon.png

 
 

modd.conf

modd.conf

 
 

requirements-docs.txt

requirements-docs.txt

 
 

requirements-test.txt

requirements-test.txt

 
 

run-tests.sh

run-tests.sh

 
 

setup.cfg

setup.cfg

 
 

setup.py

setup.py

 
 

tox.ini

tox.ini

 
 

Repository files navigation

Alfred-Workflow

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

Build Status Coverage Status Latest Version Development Status Supported Python Versions

Supports OS X 10.6+ and Python 2.6 and 2.7 (Alfred 3 is 10.9+/2.7 only).

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

The only library, in any language, that always supports all current Alfred features.

Features

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

Alfred 3-only features

  • Set workflow variables from code
  • Advanced modifiers
  • Alfred 3-only updates (won't break Alfred 2 installs)
  • Re-running of Script Filters

Contents

Installation

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's directory as described below. Do not ask users to install anything into their system Python. Python installations cannot support multiple versions of the same library, so if you rely on globally-installed libraries, the chances are very good that your workflow will sooner or later break—or be broken by—some other software doing the same naughty thing.

With pip

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

# from your workflow directory
pip install --target=. Alfred-Workflow

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

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

From source

  1. Download the alfred-workflow-X.X.X.zip from the GitHub releases page.
  2. Extract the ZIP archive and place the workflow directory in the root folder of your workflow (where info.plist is).

Your workflow should look something like this:

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

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

Usage

A few examples of how to use Alfred-Workflow.

Workflow script skeleton

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

# Workflow3 supports Alfred 3's new features. The `Workflow` class
# is also compatible with Alfred 2.
from workflow import Workflow3


def main(wf):
    # The Workflow3 instance will be passed to the function
    # you call from `Workflow3.run`.
    # Not super useful, as the `wf` object created in
    # the `if __name__ ...` clause below is global...
    #
    # Your imports go here if you want to catch import errors, which
    # is not a bad idea, or if the modules/packages are in a directory
    # added via `Workflow3(libraries=...)`
    import somemodule
    import anothermodule

    # Get args from Workflow3, already in normalized Unicode.
    # This is also necessary for "magic" arguments to work.
    args = wf.args

    # Do stuff here ...

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

    # Send output to Alfred. You can only call this once.
    # Well, you *can* call it multiple times, but subsequent calls
    # are ignored (otherwise the JSON sent to Alfred would be invalid).
    wf.send_feedback()


if __name__ == '__main__':
    # Create a global `Workflow3` object
    wf = Workflow3()
    # Call your entry function via `Workflow3.run()` to enable its
    # helper functions, like exception catching, ARGV normalization,
    # magic arguments etc.
    sys.exit(wf.run(main))

Examples

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()

Web

Grab data from a JSON web API:

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

Post a form:

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

Upload a file:

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

WARNING: As this module is based on Python 2's standard HTTP libraries, on older versions of OS X/Python, it does not 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.

Keychain access

Save password:

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

Retrieve password:

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

Documentation

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

Dash docset

The documentation is also available as a Dash docset.

Licensing, thanks

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

The documentation was generated using Sphinx and a modified version of the Alabaster theme by bitprophet.

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

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

Contributing

Adding a workflow to the list

If you want to add a workflow to the list of workflows using Alfred-Workflow, don't add it to this README! The list is machine-generated from Packal.org and the library_workflows.tsv file. If your workflow is available on Packal, it will be added automatically. If not, please add it to library_workflows.tsv, instead of README.md, and submit a corresponding pull request.

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

Bug reports, pull requests

Bug reports, feature suggestions and pull requests are very welcome. Head over to the issues if you have a feature request or a bug report.

Please note: that the only supported versions of Python are the Apple system Pythons installed on OS X 10.6+ (i.e. /usr/bin/python). Any pull requests that break compatibility with these Pythons will be rejected out of hand.

Compatibility with other Pythons is a very low priority. Pull requests adding compatibility with other Pythons will be rejected if they add significant complexity or additional dependencies, such as six.

If you want to make a pull request, do that here, but please bear the following in mind:

  • Please open pull requests against the develop branch. I try to keep master in sync with the latest release (at least regarding any files included in releases). master and develop are usually in sync, but if I'm working on new features, they'll be in develop and won't be pushed to master until they're ready for release.
  • Alfred-Workflow has very close to 100% test coverage. "Proof-of-concept" pull requests without tests are more than welcome. However, please be prepared to add the appropriate tests if you want your pull request to be ultimately accepted.
  • Complete coverage is only a proxy for decent tests. Tests should also cover a decent variety of valid/invalid input. For example, if the code could potentially be handed non-ASCII input, it should be tested with non-ASCII input.
  • Code should be PEP8-compliant as far as is reasonable. Any decent code editor has a PEP8 plugin that will warn you of potential transgressions.
  • Please choose your function, method and argument names carefully, with an eye to the existing names. Obviousness is more important than brevity.
  • Document your code using the Sphinx ReST format. Even if your function/method isn't user-facing, some other developer will be looking at it. Even if it's only a one-liner, the developer may be looking at the docs in a browser, not at the source code. If you don't feel comfortable writing English, I'd be happy to write the docs for you, but please ensure the code is easily understandable (i.e. comment the code if it's not totally obvious).
  • Performance counts. By default, Alfred will try to run a workflow anew on every keypress. As a rule, 0.3 seconds execution time is decent, 0.2 seconds or less is smooth. Alfred-Workflow should do its utmost to consume as little of that time as possible.

The main entry point for unit testing is the run-tests.sh script in the root directory. This will fail if code coverage is < 100%. Travis-CI also uses this script. Add # pragma: no cover with care.

Contributors

Tests

Alfred-Workflow includes a full suite of unit tests. Please use the run-tests.sh script in the root directory of the repo to run the unit tests: it creates the necessary test environment to run the unit tests. test_workflow.py will fail if not run via run-scripts.sh, but the test suites for the other modules may also be run directly.

Moreover, run-tests.sh checks the coverage of the unit tests and will fail if it is below 100%.

Workflows using Alfred-Workflow

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

About

Full-featured library for writing Alfred workflows

www.deanishe.net/alfred-workflow/

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

70 tags

Packages

No packages published

Languages

  • Python 76.7%
  • HTML 21.8%
  • Shell 1.5%