Alfred-Workflow 1.40.0
Full-featured helper library for writing Alfred 2/3/4 workflows
Keywords: alfred workflow alfred4

A helper library for writing `Alfred 2, 3 and 4`_ workflows.

Supports macOS 10.7+ and Python 2.7 (Alfred 3 is 10.9+/2.7 only).

Alfred-Workflow is designed to take the grunt work out of writing a workflow.

It gives you the tools to create a fast and featureful Alfred workflow from an
API, application or library in minutes.

http://www.deanishe.net/alfred-workflow/


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 (and syncing) of passwords, API keys etc.
* Simple generation of Alfred feedback (XML output)
* Input/output decoding for handling non-ASCII text
* Lightweight web API with modelled on `requests`_
* 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.
* Post notifications via Notification Center.


Alfred 3-only features
----------------------

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


Quick Example
=============

Here's how to show recent `Pinboard.in <https://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``):


.. code-block:: python

    import sys
    from workflow import Workflow, ICON_WEB, web

    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.


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


From source
-----------

Download the ``alfred-workflow-X.X.X.zip`` file from the `GitHub releases`_
page and extract the ZIP to the root directory of your workflow (where
``info.plist`` is).

Alternatively, you can download `the source code`_ from the
`GitHub repository`_ and copy the ``workflow`` subfolder to the root
directory of your workflow.

Your workflow directory should look something like this (where
``yourscript.py`` contains your workflow code and ``info.plist`` is
the workflow information file generated by Alfred)::

    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.


Documentation
=============

Detailed documentation, including a tutorial, is available at
http://www.deanishe.net/alfred-workflow/.

.. _v2 branch: https://github.com/deanishe/alfred-workflow/tree/v2
.. _requests: http://docs.python-requests.org/en/latest/
.. _Alfred 2, 3 and 4: http://www.alfredapp.com/
.. _GitHub releases: https://github.com/deanishe/alfred-workflow/releases
.. _the source code: https://github.com/deanishe/alfred-workflow/archive/master.zip
.. _GitHub repository: https://github.com/deanishe/alfred-workflow
.. _Cheese Shop: https://pypi.python.org/pypi
.. _pip documentation: https://pip.pypa.io/en/latest/
.. _workflow variables: http://www.deanishe.net/alfred-workflow/user-manual/workflow-variables.html