{"id":13478855,"url":"https://github.com/deanishe/alfred-workflow","last_synced_at":"2025-05-14T12:10:56.793Z","repository":{"id":14345443,"uuid":"17055028","full_name":"deanishe/alfred-workflow","owner":"deanishe","description":"Full-featured library for writing Alfred 3 \u0026 4 workflows","archived":false,"fork":false,"pushed_at":"2023-01-10T14:43:04.000Z","size":25413,"stargazers_count":2982,"open_issues_count":21,"forks_count":238,"subscribers_count":58,"default_branch":"master","last_synced_at":"2025-04-19T09:23:13.373Z","etag":null,"topics":["alfred","alfred-3","alfred-workflow","alfred3","alfred4","alfred4-workflow","caching","fuzzy-search","http","keychain","python","workflow","workflows"],"latest_commit_sha":null,"homepage":"https://www.deanishe.net/alfred-workflow/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deanishe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.rst","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-21T11:58:19.000Z","updated_at":"2025-04-18T05:07:44.000Z","dependencies_parsed_at":"2023-01-11T20:48:32.428Z","dependency_job_id":null,"html_url":"https://github.com/deanishe/alfred-workflow","commit_stats":null,"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deanishe%2Falfred-workflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deanishe%2Falfred-workflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deanishe%2Falfred-workflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deanishe%2Falfred-workflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deanishe","download_url":"https://codeload.github.com/deanishe/alfred-workflow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140760,"owners_count":22021219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alfred","alfred-3","alfred-workflow","alfred3","alfred4","alfred4-workflow","caching","fuzzy-search","http","keychain","python","workflow","workflows"],"created_at":"2024-07-31T16:02:04.552Z","updated_at":"2025-05-14T12:10:56.769Z","avatar_url":"https://github.com/deanishe.png","language":"Python","funding_links":[],"categories":["Python","Libraries","http"],"sub_categories":[],"readme":"\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./icon.png\" alt=\"Alfred-Workflow logo\" height=\"200\"\u003e\n\u003c/div\u003e\n\nAlfred-Workflow\n===============\n\nA helper library in Python for authors of workflows for [Alfred 3 and 4][alfred].\n\n\u003c!-- [![Build Status][shield-travis]][travis] --\u003e\n[![Build Status][shield-github]][action-github]\n[![Coverage Status][shield-coveralls]][coveralls]\n[![Development Status][shield-status]][pypi]\n[![Latest Version][shield-version]][pypi]\n[![Supported Python Versions][shield-pyversions]][pypi]\n\n\u003c!-- [![Downloads][shield-download]][pypi] --\u003e\n\nSupports Alfred 3 and Alfred 4 on macOS 10.7+ (Python 2.7).\n\nAlfred-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.\n\nAlways supports all current Alfred features.\n\n\nFeatures\n--------\n\n- Auto-saved settings API for your workflow\n- Super-simple data caching with expiry\n- Fuzzy filtering (with smart diacritic folding)\n- Keychain support for secure storage of passwords, API keys etc.\n- Lightweight web API with [Requests][requests]-like interface\n- Background tasks to keep your workflow responsive\n- Simple generation of Alfred JSON feedback\n- Full support of Alfred's AppleScript/JXA API\n- Catches and logs workflow errors for easier development and support\n- \"Magic\" arguments to help development/debugging\n- Unicode support\n- Pre-configured logging\n- Automatically check for workflow updates via GitHub releases\n- Post notifications via Notification Center\n\n\n### Alfred 4+ features ###\n\n- Advanced modifiers\n- Alfred 4-only updates (won't break older Alfred installs)\n\n\nContents\n--------\n\n\u003c!-- MarkdownTOC autolink=\"true\" bracket=\"round\" depth=\"3\" autoanchor=\"true\" --\u003e\n\n- [Installation](#installation)\n  - [With pip](#with-pip)\n  - [From source](#from-source)\n- [Usage](#usage)\n  - [Workflow script skeleton](#workflow-script-skeleton)\n  - [Examples](#examples)\n    - [Web](#web)\n    - [Keychain access](#keychain-access)\n- [Documentation](#documentation)\n  - [Dash docset](#dash-docset)\n- [Licensing, thanks](#licensing-thanks)\n- [Contributing](#contributing)\n  - [Adding a workflow to the list](#adding-a-workflow-to-the-list)\n  - [Bug reports, pull requests](#bug-reports-pull-requests)\n  - [Contributors](#contributors)\n- [Workflows using Alfred-Workflow](#workflows-using-alfred-workflow)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n\n\u003ca name=\"installation\"\u003e\u003c/a\u003e\nInstallation\n------------\n\n**Note**: If you're new to Alfred workflows, check out\n[the tutorial][docs-tutorial] in the docs.\n\n\n\u003ca name=\"with-pip\"\u003e\u003c/a\u003e\n### With pip ###\n\nYou can install Alfred-Workflow directly into your workflow with:\n\n```bash\n# from your workflow directory\npip install --target=. Alfred-Workflow\n```\n\nYou can install any other library available on the [Cheese Shop][cheeseshop] the same way. See the [pip documentation][pip-docs] for more information.\n\nIt is highly advisable to bundle all your workflow's dependencies with your workflow in this way. That way, it will \"just work\".\n\n\n\u003ca name=\"from-source\"\u003e\u003c/a\u003e\n### From source ###\n\n1. Download the `alfred-workflow-X.X.X.zip` from the [GitHub releases page][releases].\n2. Extract the ZIP archive and place the `workflow` directory in the root folder of your workflow (where `info.plist` is).\n\nYour workflow should look something like this:\n\n    Your Workflow/\n        info.plist\n        icon.png\n        workflow/\n            __init__.py\n            background.py\n            notify.py\n            Notify.tgz\n            update.py\n            version\n            web.py\n            workflow.py\n        yourscript.py\n        etc.\n\nAlternatively, you can clone/download the Alfred-Workflow [repository][repo] and copy the `workflow` subdirectory to your workflow's root directory.\n\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\nUsage\n-----\n\nA few examples of how to use Alfred-Workflow.\n\n\n\u003ca name=\"workflow-script-skeleton\"\u003e\u003c/a\u003e\n### Workflow script skeleton ###\n\nSet up your workflow scripts as follows (if you wish to use the built-in error handling or `sys.path` modification):\n\n```python\n#!/usr/bin/python\n# encoding: utf-8\n\nimport sys\n\n# Workflow3 supports Alfred 3's new features. The `Workflow` class\n# is also compatible with Alfred 2.\nfrom workflow import Workflow3\n\n\ndef main(wf):\n    # The Workflow3 instance will be passed to the function\n    # you call from `Workflow3.run`.\n    # Not super useful, as the `wf` object created in\n    # the `if __name__ ...` clause below is global...\n    #\n    # Your imports go here if you want to catch import errors, which\n    # is not a bad idea, or if the modules/packages are in a directory\n    # added via `Workflow3(libraries=...)`\n    import somemodule\n    import anothermodule\n\n    # Get args from Workflow3, already in normalized Unicode.\n    # This is also necessary for \"magic\" arguments to work.\n    args = wf.args\n\n    # Do stuff here ...\n\n    # Add an item to Alfred feedback\n    wf.add_item(u'Item title', u'Item subtitle')\n\n    # Send output to Alfred. You can only call this once.\n    # Well, you *can* call it multiple times, but subsequent calls\n    # are ignored (otherwise the JSON sent to Alfred would be invalid).\n    wf.send_feedback()\n\n\nif __name__ == '__main__':\n    # Create a global `Workflow3` object\n    wf = Workflow3()\n    # Call your entry function via `Workflow3.run()` to enable its\n    # helper functions, like exception catching, ARGV normalization,\n    # magic arguments etc.\n    sys.exit(wf.run(main))\n```\n\n\n\u003ca name=\"examples\"\u003e\u003c/a\u003e\n### Examples ###\n\nCache data for 30 seconds:\n\n```python\ndef get_web_data():\n    return web.get('http://www.example.com').json()\n\ndef main(wf):\n    # Save data from `get_web_data` for 30 seconds under\n    # the key ``example``\n    data = wf.cached_data('example', get_web_data, max_age=30)\n    for datum in data:\n        wf.add_item(datum['title'], datum['author'])\n\n    wf.send_feedback()\n```\n\n\n\u003ca name=\"web\"\u003e\u003c/a\u003e\n#### Web ####\n\nGrab data from a JSON web API:\n\n```python\ndata = web.get('http://www.example.com/api/1/stuff').json()\n```\n\nPost a form:\n\n```python\nr = web.post('http://www.example.com/',\n             data={'artist': 'Tom Jones', 'song': \"It's not unusual\"})\n```\n\nUpload a file:\n\n```python\nfiles = {'fieldname' : {'filename': \"It's not unusual.mp3\",\n                        'content': open(\"It's not unusual.mp3\", 'rb').read()}\n}\nr = web.post('http://www.example.com/upload/', files=files)\n```\n\n**WARNING**: As this module is based on Python 2's standard HTTP libraries, *on old 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][requests] library upon which the `web.py` API is based.\n\n\n\u003ca name=\"keychain-access\"\u003e\u003c/a\u003e\n#### Keychain access ####\n\nSave password:\n\n```python\nwf = Workflow()\nwf.save_password('name of account', 'password1lolz')\n```\n\nRetrieve password:\n\n```python\nwf = Workflow()\nwf.get_password('name of account')\n```\n\n\n\u003ca name=\"documentation\"\u003e\u003c/a\u003e\nDocumentation\n-------------\n\nThe full documentation, including API docs and a tutorial, can be found at [deanishe.net][docs].\n\n\n\u003ca name=\"dash-docset\"\u003e\u003c/a\u003e\n### Dash docset ###\n\nThe documentation is also available as a [Dash docset][dash].\n\n\n\u003ca name=\"licensing-thanks\"\u003e\u003c/a\u003e\nLicensing, thanks\n-----------------\n\nThe code and the documentation are released under the MIT and [Creative Commons Attribution-NonCommercial][cc] licences respectively. See [LICENCE.txt](LICENCE.txt) for details.\n\nThe documentation was generated using [Sphinx][sphinx] and a modified version of the [Alabaster][alabaster] theme by [bitprophet][bitprophet].\n\nMany of the cooler ideas in Alfred-Workflow were inspired by [Alfred2-Ruby-Template][ruby-template] by Zhaocai.\n\nThe Keychain parser was based on [Python-Keyring][python-keyring] by Jason R. Coombs.\n\n\n\u003ca name=\"contributing\"\u003e\u003c/a\u003e\nContributing\n------------\n\n\n\u003ca name=\"adding-a-workflow-to-the-list\"\u003e\u003c/a\u003e\n### Adding a workflow to the list ###\n\nIf you want to add a workflow to the [list of workflows using Alfred-Workflow][docs-workflows], **don't add it to the docs!** The list is machine-generated from [Packal.org][packal] and the [`library_workflows.tsv`](extras/library_workflows.tsv) file. If your workflow is available on [Packal][packal], it will be added on the next update. If not, please add it to [`library_workflows.tsv`](extras/library_workflows.tsv), and submit a corresponding pull request.\n\nThe 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][issues] asking me to update the list.\n\n\n\u003ca name=\"bug-reports-pull-requests\"\u003e\u003c/a\u003e\n### Bug reports, pull requests ###\n\nPlease see [the documentation][docs-contributing].\n\n\n\u003ca name=\"contributors\"\u003e\u003c/a\u003e\n### Contributors ###\n\n- [Dean Jackson][deanishe]\n- [Stephen Margheim][smargh]\n- [Fabio Niephaus][fniephaus]\n- [Owen Min][owenwater]\n\n\n\u003ca name=\"workflows-using-alfred-workflow\"\u003e\u003c/a\u003e\nWorkflows using Alfred-Workflow\n-------------------------------\n\n[Here is a list][docs-workflows] of some of the many workflows based on Alfred-Workflow.\n\n\n[alfred]: http://www.alfredapp.com/\n[awv2]: https://github.com/deanishe/alfred-workflow/tree/v2\n[alabaster]: https://github.com/bitprophet/alabaster\n[bitprophet]: https://github.com/bitprophet\n[cc]: https://creativecommons.org/licenses/by-nc/4.0/legalcode\n[coveralls]: https://coveralls.io/r/deanishe/alfred-workflow?branch=master\n[deanishe]: https://github.com/deanishe\n[docs-contributing]: http://www.deanishe.net/alfred-workflow/contributing.html\n[docs-tutorial]: http://www.deanishe.net/alfred-workflow/tutorial.html\n[docs-api]: http://www.deanishe.net/alfred-workflow/api/\n[docs]: http://www.deanishe.net/alfred-workflow/\n[docs-workflows]: http://www.deanishe.net/alfred-workflow/aw-workflows.html\n[dash]: https://github.com/deanishe/alfred-workflow/raw/master/docs/Alfred-Workflow.docset.zip\n[fniephaus]: https://github.com/fniephaus\n[owenwater]: https://github.com/owenwater\n[issues]: https://github.com/deanishe/alfred-workflow/issues\n[landscape]: https://landscape.io/github/deanishe/alfred-workflow/master\n[packal]: http://www.packal.org/\n[pep8]: http://legacy.python.org/dev/peps/pep-0008/\n[pulls]: https://github.com/deanishe/alfred-workflow/pulls\n[pypi]: https://pypi.python.org/pypi/Alfred-Workflow/\n[releases]: https://github.com/deanishe/alfred-workflow/releases\n[repo]: https://github.com/deanishe/alfred-workflow\n[requests]: http://docs.python-requests.org/en/latest/\n[rtd]: https://readthedocs.org/\n[shield-coveralls]: https://coveralls.io/repos/github/deanishe/alfred-workflow/badge.svg?branch=master\n[shield-docs]: https://readthedocs.org/projects/alfredworkflow/badge/?version=latest\u0026style=flat\n[shield-download]: https://img.shields.io/pypi/dm/Alfred-Workflow.svg?style=flat\n[shield-github]: https://github.com/deanishe/alfred-workflow/workflows/CI/badge.svg\n[action-github]: https://github.com/deanishe/alfred-workflow/actions?query=workflow%3ACI\n[shield-health]: https://landscape.io/github/deanishe/alfred-workflow/master/landscape.png?style=flat\n[shield-licence]: https://pypip.in/license/Alfred-Workflow/badge.svg?style=flat\n[shield-status]: https://img.shields.io/pypi/status/Alfred-Workflow.svg?style=flat\n[shield-travis]: https://travis-ci.org/deanishe/alfred-workflow.svg?branch=master\u0026style=flat\n[shield-version]: https://img.shields.io/pypi/v/Alfred-Workflow.svg?style=flat\n[shield-pyversions]: https://img.shields.io/pypi/pyversions/Alfred-Workflow.svg?style=flat\n[smargh]: https://github.com/smargh\n[sphinx]: http://sphinx-doc.org/\n[travis]: https://travis-ci.org/deanishe/alfred-workflow\n[cheeseshop]: https://pypi.python.org/pypi\n[pip-docs]: https://pip.pypa.io/en/latest/\n[ruby-template]: http://zhaocai.github.io/alfred2-ruby-template/\n[python-keyring]: https://pypi.python.org/pypi/keyring\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeanishe%2Falfred-workflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeanishe%2Falfred-workflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeanishe%2Falfred-workflow/lists"}