A helper library in Python for authors of workflows for Alfred 2.
- Catches and logs workflow errors for easier development and support
- "Magic" arguments to help development/debugging
- Auto-saves settings
- Super-simple data caching
- Fuzzy, Alfred-like search/filtering with diacritic folding
- Keychain support for secure storage of passwords, API keys etc.
- Simple generation of Alfred feedback (XML output)
- Input/output decoding for handling non-ASCII text
- Lightweight web API with Requests-like interface
- Pre-configured logging
- Painlessly add directories to
sys.path
- Easily launch background tasks (daemons) to keep your workflow responsive
- Check for new versions and update workflows hosted on GitHub.
- Installation
- Usage
- Documentation
- Licensing, thanks
- Contributing
- Tests
- Workflows using 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'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.
You can install Alfred-Workflow directly into your workflow with:
pip install --target=/path/to/my/workflow Alfred-Workflow
You can install any other library available on the Cheese Shop the same way. See the pip documentation for more information.
###Â From source ###
- Download the
alfred-workflow-X.X.X.zip
from the releases page. - Either extract the ZIP archive and place the
workflow
directory in the root folder of your workflow (whereinfo.plist
is) or - Place the ZIP archive in the root folder of your workflow and add
sys.path.insert(0, 'alfred-workflow-X.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.
A few examples of how to use Alfred-Workflow.
Set up your workflow scripts as follows (if you wish to use the built-in error
handling or sys.path
modification):
#!/usr/bin/python
# encoding: utf-8
import sys
from workflow import Workflow
def main(wf):
# The Workflow instance will be passed to the function
# you call from `Workflow.run`
# Your imports here if you want to catch import errors
# or if the modules/packages are in a directory added via `Workflow(libraries=...)`
import somemodule
import anothermodule
# Get args from Workflow, already in normalised Unicode
args = wf.args
# Do stuff here ...
# Add an item to Alfred feedback
wf.add_item(u'Item title', u'Item subtitle')
# Send output to Alfred
wf.send_feedback()
if __name__ == '__main__':
wf = Workflow()
sys.exit(wf.run(main))
Cache data for 30 seconds:
def get_web_data():
return web.get('http://www.example.com').json()
def main(wf):
# Save data from `get_web_data` for 30 seconds under
# the key ``example``
data = wf.cached_data('example', get_web_data, max_age=30)
for datum in data:
wf.add_item(datum['title'], datum['author'])
wf.send_feedback()
Grab data from a JSON web API:
data = web.get('http://www.example.com/api/1/stuff').json()
Post a form:
r = web.post('http://www.example.com/', data={'artist': 'Tom Jones', 'song': "It's not unusual"})
Upload a file:
files = {'fieldname' : {'filename': "It's not unusual.mp3",
'content': open("It's not unusual.mp3", 'rb').read()}
}
r = web.post('http://www.example.com/upload/', files=files)
WARNING: As this module is based on Python 2's standard HTTP libraries, it
cannot validate SSL certificates when making HTTPS connections. If your
workflow uses sensitive passwords/API keys, you should strongly consider
using the requests library upon which the web.py
API is based.
Save password:
wf = Workflow()
wf.save_password('name of account', 'password1lolz')
Retrieve password:
wf = Workflow()
wf.get_password('name of account')
The full documentation, including API docs and a tutorial, can be found here.
There is a mirror at Read the Docs.
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.
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, 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:
- Please open pull requests against the
develop
branch. I try to keepmaster
in sync with the latest release (at least regarding any files included in releases).master
anddevelop
are usually in sync, but if I'm working on new features, they'll be indevelop
and won't be pushed tomaster
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.
- 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.
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%.
These are some of the Alfred workflows that use this library.
- Alfred Backblaze (GitHub repo) by XedMada (on GitHub). Pause and Start Backblaze online backups.
- Alfred Dependency Bundler Demo (Python) (GitHub repo) by deanishe (on GitHub). Demonstration on how to use the Alfred Bundler in Python.
- alfred-ime (GitHub repo) by owenwater (on GitHub). A Input method workflow based on Google Input Tools.
- AppScripts (GitHub repo) by deanishe (on GitHub). List, search and run/open AppleScripts for the active application.
- Better IMDB search by frankspin. Search IMDB for movies and see results inside of Alfred.
- BibQuery (GitHub repo) by hackademic (on GitHub). Search BibDesk from the comfort of your keyboard.
- Blur by Tyler Eich. Set Alfred's background blur radius.
- Code Case by dfay. Case Converter for Code.
- Continuity Support by dmarshall. Enables calling and messaging via contacts or number input.
- Convert (GitHub repo) by deanishe (on GitHub). Convert between different units. No Internet connection required.
- Date Calculator (GitHub repo) by MuppetGate (on GitHub). A basic date calculator.
- Digital Ocean status (GitHub repo) by frankspin (on GitHub). Control your Digital Ocean droplets.
- Display Brightness (GitHub repo) by fniephaus (on GitHub). Adjust your display's brightness with Alfred.
- Dropbox Client for Alfred (GitHub repo) by fniephaus (on GitHub). Access multiple Dropbox accounts with Alfred.
- Duden Search (GitHub repo) by deanishe (on GitHub). Search duden.de German dictionary (with auto-suggest).
- Fabric for Alfred by fniephaus. Quickly execute Fabric tasks.
- Fuzzy Folders (GitHub repo) by deanishe (on GitHub). Fuzzy search across folder subtrees.
- Git Repos (GitHub repo) by deanishe (on GitHub). Browse, search and open Git repositories from within Alfred.
- Glosbe Translation by deanishe. Translate text using Glosbe.com.
- Gmail Client for Alfred (GitHub repo) by fniephaus (on GitHub). Manage your Gmail inbox with Alfred.
- HackerNews for Alfred (GitHub repo) by fniephaus (on GitHub). Read Hacker News with Alfred.
- Homebrew and Cask for Alfred (GitHub repo) by fniephaus (on GitHub). Easily control Homebrew and Cask with Alfred.
- IPython Notebooks (GitHub repo) by nkeim (on GitHub). Search notebook titles on your IPython notebook server.
- Jenkins (GitHub repo) by Amwam (on GitHub). Show and search through jobs on Jenkins.
- KA Torrents by hackademic. Search and download torrents from kickass.so.
- Laser SSH by paperElectron. Choose SSH connection from filterable list.
- LibGen (GitHub repo) by hackademic (on GitHub). Search and Download pdfs and ebooks from Library Genesis.
- Network Location (GitHub repo) by deanishe (on GitHub). List, filter and activate network locations from within Alfred.
- Packal Workflow Search (GitHub repo) by deanishe (on GitHub). Search Packal.org from the comfort of Alfred.
- Pandoctor (GitHub repo) by hackademic (on GitHub). An Alfred GUI for Pandoc.
- Parsers (GitHub repo) by hackademic (on GitHub). Greek and Latin parsers.
- Percent Change (GitHub repo) by bkmontgomery (on GitHub). Easily do percentage calculations.
- Pocket for Alfred (GitHub repo) by fniephaus (on GitHub). Manage your Pocket list with Alfred.
- PWS History (GitHub repo) by hrbrmstr (on GitHub). Retrieve personal weather station history from Weather Underground.
- Quick Stocks by paperElectron. Add some stock symbols for Alfred to check for you.
- Readability for Alfred (GitHub repo) by fniephaus (on GitHub). Manage your Readability list with Alfred.
- Relative Dates by deanishe. Generate relative dates based on a simple input format.
- Resolve URL (GitHub repo) by deanishe (on GitHub). Follows any HTTP redirects and returns the canonical URL. Also displays information about the primary host (hostname, IP address(es), aliases).
- Searchio! (GitHub repo) by deanishe (on GitHub). Auto-suggest search results from multiple search engines and languages.
- SEND by hackademic. Send documents to the cloud.
- Skimmer (GitHub repo) by hackademic (on GitHub). Actions for PDF viewer Skim.
- slackfred (GitHub repo) by frankspin (on GitHub). Interact with the chat service Slack via Alfred.
- Snippets (GitHub repo) by hackademic (on GitHub). Simple, document-specific text snippets.
- Spritzr (GitHub repo) by hackademic (on GitHub). An Alfred Speed-Reader.
- Sublime Text Projects (GitHub repo) by deanishe (on GitHub). View, filter and open your Sublime Text (2 and 3) project files.
- Torrent (GitHub repo) by bfw (on GitHub). Search for torrents, choose among the results in Alfred and start the download in uTorrent.
- Travis CI for Alfred by fniephaus. Quickly check build statuses on travis-ci.org.
- UberTime (GitHub repo) by frankspin (on GitHub). Check estimated pick up time for Uber based on inputted address.
- VagrantUP (GitHub repo) by m1keil (on GitHub). List and control Vagrant environments with Alfred2.
- VM Control (GitHub repo) by fniephaus (on GitHub). Control your Parallels and Virtual Box virtual machines.
- Wikify (GitHub repo) by hackademic (on GitHub). Your little Evernote Wiki-Helper.
- ZotQuery (GitHub repo) by hackademic (on GitHub). Search Zotero. From the Comfort of Your Keyboard.