Skip to content

index.rst

Latest commit

 

History

History
275 lines (187 loc) · 8.12 KB

index.rst

File metadata and controls

275 lines (187 loc) · 8.12 KB
Raw

Overview

Build Status Code Coverage Latest Version Development Status Supported Python Versions

Go to :ref:`Quick Index <quickindex>`.

Alfred-Workflow is a Python helper library for Alfred 2 and 3 workflow authors, developed and hosted on GitHub.

Alfred workflows typically take user input, fetch data from the Web or elsewhere, filter them and display results to the user. Alfred-Workflow takes care of a lot of the details for you, allowing you to concentrate your efforts on your workflow's functionality.

Alfred-Workflow supports OS X 10.6+ (Python 2.6 and 2.7).

Features

  • Catches and logs workflow errors for easier development and support
  • :ref:`"Magic" arguments <magic-arguments>` to help development, debugging and management of the workflow
  • :ref:`Auto-saves settings <manual-settings>`
  • Super-simple :ref:`data caching <caching-data>`
  • Fuzzy, :ref:`Alfred-like search/filtering <filtering>` with :ref:`diacritic folding <folding>`
  • :ref:`Keychain support <keychain>` for secure storage (and syncing) of passwords, API keys etc.
  • Simple generation of Alfred feedback (XML output)
  • :ref:`Input/output decoding <text-encoding>` for handling non-ASCII text
  • :ref:`Lightweight web <web>` API with Requests-like interface
  • Pre-configured logging
  • Painlessly add directories to sys.path
  • Easily launch :ref:`background tasks <background-processes>` (daemons) to keep your workflow responsive
  • :ref:`Check for and install new workflow versions <manual-updates>` using GitHub releases
  • :ref:`Post notifications <notifications>` with Notification Center (10.8+ only)

Alfred 3-only features

  • Set :ref:`workflows variables <workflow-variables>` from code
  • Advanced modifiers
  • Alfred 3-only updates (won't break Alfred 2 installs)

Quick example

Here's how to show recent Pinboard.in posts in Alfred.

Create a new workflow in Alfred's preferences. Add a Script Filter with Language /usr/bin/python and paste the following into the Script field (changing API_KEY):

import sys
from workflow import Workflow, ICON_WEB, web
# To use Alfred 3's feedback mechanism:
# from workflow import Workflow3

API_KEY = 'your-pinboard-api-key'

def main(wf):
    url = 'https://api.pinboard.in/v1/posts/recent'
    params = dict(auth_token=API_KEY, count=20, format='json')
    r = web.get(url, params)
    r.raise_for_status()
    for post in r.json()['posts']:
        wf.add_item(post['description'], post['href'], arg=post['href'],
                    uid=post['hash'], valid=True, icon=ICON_WEB)
    wf.send_feedback()


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

Add an Open URL action to your workflow with {query} as the URL, connect your Script Filter to it, and you can now hit ENTER on a Pinboard item in Alfred to open it in your browser.

Warning

Using the above example code as a workflow will likely get you banned by the Pinboard API. See the :ref:`tutorial` if you want to build an API terms-compliant (and super-fast) Pinboard workflow.

Supported software

Alfred-Workflow supports all versions of Alfred 2 and all versions of OS X supported by Alfred 2. It works with Python 2.6 and 2.7, but not Python 3.

Some features are not available on older versions of OS X.

.. toctree::
  :maxdepth: 2

  supported-versions

Installation

Alfred-Workflow can be installed from the Python Package Index with pip or from the source on GitHub.

.. toctree::
    :maxdepth: 2

    installation

The Alfred-Workflow Tutorial

A :ref:`two-part tutorial <tutorial>` on writing an Alfred workflow with Alfred-Workflow, taking you through the basics to a performant and release- ready workflow. This is the best starting point for workflow authors new to Python or programming in general. More experienced Python coders should skim this or skip straight ahead to the :ref:`user-manual`.

.. toctree::
    :maxdepth: 2

    tutorial

User Manual

If you know your way around Python and Alfred, here's an overview of what Alfred-Workflow can do and how to do it.

.. toctree::
   :maxdepth: 2

   user-manual/index

API documentation

Documetation of the Alfred-Workflow APIs generated from the source code. A handy reference if (like me) you sometimes forget parameter names.

.. toctree::
  :maxdepth: 2

  api/index

Script Filter results and the XML format

An in-depth look at Alfred's XML format, the many parameters accepted by :meth:`Workflow.add_item() <workflow.workflow.Workflow.add_item>` and how they interact with one another.

Note

This should also serve as a decent reference to Alfred's XML format for folks who aren't using Alfred-Workflow. The official Alfred 2 XML docs have recently seen a massive update, but historically haven't been very up-to-date.

.. toctree::
   :maxdepth: 3

   xml_format

Workflows using Alfred-Workflow

This is a list of some of the workflows based on Alfred-Workflow.

.. toctree::
   :maxdepth: 2

   aw-workflows

Feedback, questions, bugs, feature requests

If you have feedback or a question regarding Alfred-Workflow, please post in them in the Alfred forum thread.

If you have a bug report or a feature request, please create a new issue on GitHub.

You can also email me at deanishe@deanishe.net with any questions/feedback/bug reports. However, it's generally better to use the forum/GitHub so that other users can benefit from and contribute to the conversation.

Quick Index

The Quick Index is a list of links to all the interesting parts of the documentation.

.. toctree::
    :maxdepth: 1

    quickindex

Indices and tables

  • :ref:`genindex`
  • :ref:`modindex`
  • :ref:`search`