Skip to content
/ alfred-workflow Public
forked from deanishe/alfred-workflow

Helper library for writing Alfred 2 workflows in Python

License

View license
0 stars 236 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

hortocam/alfred-workflow

BranchesTags
 
 

Repository files navigation

Alfred-Workflow

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

Build Status Coverage Status Code Health Latest Version Documentation Status License Downloads

Features

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

Contents

Installation

With pip

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

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

Note: If you intend to distribute your workflow to other users, you should include Alfred-Workflow (and other Python libraries your workflow requires) within your workflow as described. Do not ask users to install anything into their system Python.

### From source ###

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

Your workflow should look something like this:

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

Or this:

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

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

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

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

from workflow import Workflow


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

    # Do stuff here ...

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

    # Send output to Alfred
    wf.send_feedback()


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

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, it cannot validate SSL certificates when making HTTPS connections. If your workflow uses sensitive passwords/API keys, you should strongly consider using the requests library upon which the web.py API is based.

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 here.

There is a mirror at Read the Docs.

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 using the Read the Docs theme.

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 automatically generated from Packal.org and the library_workflows.tsv file. If your workflow is available on Packal, it should be added automatically. If not, please add it to library_workflows.tsv, instead of README.md, and submit a corresponding pull request.

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.

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

  • 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.
  • Performance counts. 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.

Currently, there is Travis-CI integration, but also a run-tests.sh script in the root directory of the repo which will fail if code coverage is less than 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

Helper library for writing Alfred 2 workflows in Python

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

28 tags

Packages

No packages published