Merge branch 'release/v1.10.0'

README.md

@@ -306,15 +306,16 @@ These are some of the Alfred workflows that use this library.
   by [XedMada](http://www.packal.org/users/xedmada)
   ([on GitHub](https://github.com/XedMada/)).
   Pause and Start Backblaze online backups.
-- [alfred-ime](http://www.packal.org/workflow/alfred-ime)
-  ([GitHub repo](https://github.com/owenwater/alfred-ime))
-  by [owenwater](http://www.packal.org/users/owenwater)
-  ([on GitHub](https://github.com/owenwater/)).
 - [Alfred Dependency Bundler Demo (Python)](http://www.packal.org/workflow/alfred-dependency-bundler-demo-python)
   ([GitHub repo](https://github.com/deanishe/alfred-bundler-python-demo))
   by [deanishe](http://www.packal.org/users/deanishe)
   ([on GitHub](https://github.com/deanishe/)).
   Demonstration on how to use the Alfred Bundler in Python.
+- [alfred-ime](http://www.packal.org/workflow/ime)
+  ([GitHub repo](https://github.com/owenwater/alfred-ime))
+  by [owenwater](http://www.packal.org/users/owenwater)
+  ([on GitHub](https://github.com/owenwater/)).
+  A Input method workflow based on Google Input Tools.
 - [AppScripts](http://www.packal.org/workflow/appscripts)
   ([GitHub repo](https://github.com/deanishe/alfred-appscripts))
   by [deanishe](http://www.packal.org/users/deanishe)
@@ -334,6 +335,9 @@ These are some of the Alfred workflows that use this library.
 - [Code Case](http://www.packal.org/workflow/code-case)
   by [dfay](http://www.packal.org/users/dfay).
   Case Converter for Code.
+- [Continuity Support](http://www.packal.org/workflow/continuity-support)
+  by [dmarshall](http://www.packal.org/users/dmarshall).
+  Enables calling and messaging via contacts or number input.
 - [Convert](http://www.packal.org/workflow/convert)
   ([GitHub repo](https://github.com/deanishe/alfred-convert))
   by [deanishe](http://www.packal.org/users/deanishe)
@@ -380,8 +384,10 @@ These are some of the Alfred workflows that use this library.
 - [Glosbe Translation](http://www.packal.org/workflow/glosbe-translation)
   by [deanishe](http://www.packal.org/users/deanishe).
   Translate text using Glosbe.com.
-- [Gmail for Alfred](https://github.com/fniephaus/alfred-gmail)
-  by [fniephaus](https://github.com/fniephaus/).
+- [Gmail Client for Alfred](http://www.packal.org/workflow/gmail-client-alfred)
+  ([GitHub repo](https://github.com/fniephaus/alfred-gmail))
+  by [fniephaus](http://www.packal.org/users/fniephaus)
+  ([on GitHub](https://github.com/fniephaus/)).
   Manage your Gmail inbox with Alfred.
 - [HackerNews for Alfred](http://www.packal.org/workflow/hackernews-alfred)
   ([GitHub repo](https://github.com/fniephaus/alfred-hackernews))
@@ -403,6 +409,9 @@ These are some of the Alfred workflows that use this library.
   by [Amwam](http://www.packal.org/users/amwam)
   ([on GitHub](https://github.com/Amwam/)).
   Show and search through jobs on Jenkins.
+- [KA Torrents](http://www.packal.org/workflow/ka-torrents)
+  by [hackademic](http://www.packal.org/users/hackademic).
+  Search and download torrents from kickass.so.
 - [Laser SSH](http://www.packal.org/workflow/laser-ssh)
   by [paperElectron](http://www.packal.org/users/paperelectron).
   Choose SSH connection from filterable list.
@@ -416,11 +425,6 @@ These are some of the Alfred workflows that use this library.
   by [deanishe](http://www.packal.org/users/deanishe)
   ([on GitHub](https://github.com/deanishe/)).
   List, filter and activate network locations from within Alfred.
-- [PWS History](http://www.packal.org/workflow/pws-history)
-  ([GitHub repo](https://github.com/hrbrmstr/alfred-pws))
-  by [hrbrmstr](http://www.packal.org/users/hrbrmstr)
-  ([on GitHub](https://github.com/hrbrmstr/)).
-  Retrieve personal weather station history from Weather Underground.
 - [Packal Workflow Search](http://www.packal.org/workflow/packal-workflow-search)
   ([GitHub repo](https://github.com/deanishe/alfred-packal-search))
   by [deanishe](http://www.packal.org/users/deanishe)
@@ -446,6 +450,11 @@ These are some of the Alfred workflows that use this library.
   by [fniephaus](http://www.packal.org/users/fniephaus)
   ([on GitHub](https://github.com/fniephaus/)).
   Manage your Pocket list with Alfred.
+- [PWS History](http://www.packal.org/workflow/pws-history)
+  ([GitHub repo](https://github.com/hrbrmstr/alfred-pws))
+  by [hrbrmstr](http://www.packal.org/users/hrbrmstr)
+  ([on GitHub](https://github.com/hrbrmstr/)).
+  Retrieve personal weather station history from Weather Underground.
 - [Quick Stocks](http://www.packal.org/workflow/quick-stocks)
   by [paperElectron](http://www.packal.org/users/paperelectron).
   Add some stock symbols for Alfred to check for you.
@@ -462,14 +471,14 @@ These are some of the Alfred workflows that use this library.
   by [deanishe](http://www.packal.org/users/deanishe)
   ([on GitHub](https://github.com/deanishe/)).
   Follows any HTTP redirects and returns the canonical URL. Also displays information about the primary host (hostname, IP address(es), aliases).
-- [SEND](http://www.packal.org/workflow/send)
-  by [hackademic](http://www.packal.org/users/hackademic).
-  Send documents to the cloud.
 - [Searchio!](http://www.packal.org/workflow/searchio)
   ([GitHub repo](https://github.com/deanishe/alfred-searchio))
   by [deanishe](http://www.packal.org/users/deanishe)
   ([on GitHub](https://github.com/deanishe/)).
   Auto-suggest search results from multiple search engines and languages.
+- [SEND](http://www.packal.org/workflow/send)
+  by [hackademic](http://www.packal.org/users/hackademic).
+  Send documents to the cloud.
 - [Skimmer](http://www.packal.org/workflow/skimmer)
   ([GitHub repo](https://github.com/smargh/alfred-Skimmer))
   by [hackademic](http://www.packal.org/users/hackademic)
@@ -508,16 +517,16 @@ These are some of the Alfred workflows that use this library.
   by [frankspin](http://www.packal.org/users/frankspin)
   ([on GitHub](https://github.com/fspinillo/)).
   Check estimated pick up time for Uber based on inputted address.
-- [VM Control](http://www.packal.org/workflow/vm-control)
-  ([GitHub repo](https://github.com/fniephaus/alfred-vmcontrol))
-  by [fniephaus](http://www.packal.org/users/fniephaus)
-  ([on GitHub](https://github.com/fniephaus/)).
-  Control your Parallels and Virtual Box virtual machines.
 - [VagrantUP](http://www.packal.org/workflow/vagrantup)
   ([GitHub repo](https://github.com/m1keil/alfred-vagrant-workflow))
   by [m1keil](http://www.packal.org/users/m1keil)
   ([on GitHub](https://github.com/m1keil/)).
   List and control Vagrant environments with Alfred2.
+- [VM Control](http://www.packal.org/workflow/vm-control)
+  ([GitHub repo](https://github.com/fniephaus/alfred-vmcontrol))
+  by [fniephaus](http://www.packal.org/users/fniephaus)
+  ([on GitHub](https://github.com/fniephaus/)).
+  Control your Parallels and Virtual Box virtual machines.
 - [Wikify](http://www.packal.org/workflow/wikify)
   ([GitHub repo](https://github.com/smargh/alfred_EN-Wikify))
   by [hackademic](http://www.packal.org/users/hackademic)
@@ -528,8 +537,6 @@ These are some of the Alfred workflows that use this library.
   by [hackademic](http://www.packal.org/users/hackademic)
   ([on GitHub](https://github.com/smargh/)).
   Search Zotero. From the Comfort of Your Keyboard.
-  A Input method workflow based on Google Input Tools.
-
 
 
 [alfred]: http://www.alfredapp.com/

TODO

@@ -15,11 +15,12 @@ Features to Add:
 
 	web.py:
 
-
 	workflow.py:
+		- Add `first_run()` to determine if the workflow has been run on this computer before. @priority(1)
+		Save a "flag" in the data directory upon first run.
+		Should the file only be created the first time `first_run()` is called instead?
+		How about being able to pass a version argument to `first_run()`?
 		- `filter()` should warn when comparing Unicode and `str` objects @priority(3)
-		- move "magic" args to class-level dictionary, so authors can add their own. @priority(2) @v2
-		- `filter()` should replace "smart" punctuation with dumb equivalents @priority(1)
 		- `max_age` argument of `cached_data()` should default to 0 (always return cached data) @v2 @priority(1)
 
 
@@ -64,10 +65,6 @@ Features to Consider:
 
 
 	workflow.py:
-		- Add `first_run()` to determine if the workflow has been run on this computer before.
-		Save a "flag" in the data directory upon first run.
-		Should the file only be created the first time `first_run()` is called instead?
-		How about being able to pass a version argument to `first_run()`?
 		- automatically add `lib` and/or `packages` subdirectory to `sys.path`
 		- Add `TechnicolorLogger` formatter
 
@@ -79,12 +76,18 @@ General:
 
 ＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿
 Archive:
-	- Integrate Fabio's update feature @done(14-09-14 19:50) @project(Features to Add / update.py)
-	- Allow omission of `v` in version specified in `update_settings` @done(14-09-14 22:14) @project(Features to Add / update.py)
-	- Perform download & installation in the background, so Workflow can inform user that an update is being performed @priority(1) @done(14-09-25 11:57) @project(Features to Add / update.py)
+	- `filter()` should replace "smart" punctuation with dumb equivalents @priority(1) @done(14-12-20 14:17) @project(Features to Add / workflow.py)
+	- move "magic" args to class-level dictionary, so authors can add their own. @priority(2) @v2 @done(14-12-20 14:17) @project(Features to Add / workflow.py)
+	- Allow users to turn off automatic update checks @done(14-12-20 11:20) @project(Features to Add / update.py)
+	- Add `help_url`. Will be shown in log when an error occurs and can be opened via `workflow:help` magic arg. @done(14-12-20 10:39) @project(Features to Add / workflow.py)
+	- Handle gzip-encoded HTTP data @done(14-12-20 10:34) @project(Features to Add / web.py)
+	- Add `save_to_path()` method to save HTTP data directly to disk @done(14-12-20 10:34) @project(Features to Add / web.py)
 	- Improve description of how to use `Workflow(libraries=)` @done(14-09-25 11:59) @project(Features to Add / Docs)
 		Make paths to specify to `pip` clearer.
 		See https://github.com/deanishe/alfred-workflow/issues/28
+	- Perform download & installation in the background, so Workflow can inform user that an update is being performed @priority(1) @done(14-09-25 11:57) @project(Features to Add / update.py)
+	- Allow omission of `v` in version specified in `update_settings` @done(14-09-14 22:14) @project(Features to Add / update.py)
+	- Integrate Fabio's update feature @done(14-09-14 19:50) @project(Features to Add / update.py)
 	- Move documentation out of module docstrings into ReST files under /doc @priority(1) @done(14-09-14 14:23) @project(Features to Add / Docs)
 		A lot of the documentation isn't super-suitable for Python's `help()`
 		function. The published HTML documentation could be much better arranged

docs/api/update.rst

@@ -9,16 +9,19 @@ Self-Updating
 .. versionadded:: 1.9
 
 Add self-updating capabilities to your workflow. It regularly (every day
-by default) fetches the latest releases from the specified GitHub repository
-and then asks the user if they want to replace the workflow if a newer version
-is available.
+by default) fetches the latest releases from the specified GitHub repository.
 
 Currently, only updates from
 `GitHub releases <https://help.github.com/categories/85/articles>`_ are
 supported.
 
+.. note::
+
+	Alfred-Workflow will check for updates, but will neither install them nor
+	notify the user that an update is available.
+
 Please see :ref:`manual-updates` in the :ref:`user-manual` for information on how
-to enable automatic updates.
+to enable automatic updates in your workflow.
 
 API
 ---

docs/user-manual/filtering.rst

@@ -228,6 +228,18 @@ Users may override a Workflow's default settings via ``workflow:folding…``
 :ref:`magic arguments <magic-arguments>`.
 
 
+.. _smart-punctuation:
+
+"Smart" punctuation
+^^^^^^^^^^^^^^^^^^^
+
+The default diacritic folding only alters letters, not punctuation. If your
+workflow also works with text that contains so-called "smart" (i.e. curly)
+quotes or n- and m-dashes, you can use the :meth:`Workflow.dumbify_punctuation() <workflow.workflow.Workflow.dumbify_punctuation>`
+method to replace smart quotes and dashes with normal quotes and hyphens
+respectively.
+
+
 .. _matching-rules:
 
 Matching rules

docs/user-manual/index.rst

@@ -5,7 +5,7 @@
 User Manual
 ===========
 
-This section describes how to use the features of **Alfred-Python**.
+This section describes how to use the features of Alfred-Workflow.
 
 If you're new to writing workflows or coding in general, start with the
 :ref:`Tutorial <tutorial>`.
@@ -21,6 +21,7 @@ If you're new to writing workflows or coding in general, start with the
    web
    background
    update
+   versioning
    icons
    magic-args
    serialization

docs/user-manual/magic-args.rst

@@ -29,8 +29,11 @@ for debugging.
     the :attr:`~workflow.workflow.Workflow.args` property (where magic
     arguments are parsed).
 
-:class:`~workflow.workflow.Workflow` supports the following magic arguments:
+:class:`~workflow.workflow.Workflow` supports the following magic arguments by default:
 
+- ``workflow:magic`` — List available magic arguments.
+- ``workflow:help`` — Open workflow's help URL in default web browser. This URL is specified in the ``help_url`` argument to :class:`~workflow.workflow.Workflow`.
+- ``workflow:version`` — Display the installed version of the workflow (if one is set).
 - ``workflow:delcache`` — Delete the Workflow's cache.
 - ``workflow:deldata`` — Delete the Workflow's saved data.
 - ``workflow:delsettings`` — Delete the Workflow's settings file (which contains the data stored using :attr:`Workflow.settings <workflow.workflow.Workflow.settings>`).
@@ -44,16 +47,18 @@ for debugging.
 - ``workflow:openworkflow`` — Open the Workflow's root directory (where ``info.plist`` is).
 - ``workflow:reset`` — Delete the Workflow's settings, cache and saved data.
 - ``workflow:update`` — Check for a newer version of the workflow using GitHub releases and install the newer version if one is available.
+- ``workflow:noautoupdate`` — Turn off automatic checks for updates.
+- ``workflow:autoupdate`` — Turn automatic checks for updates on.
 
 The three ``workflow:folding…`` settings allow users to override the diacritic
 folding set by a workflow's author. This may be useful if the author's choice
 does not correspond with a user's usage pattern.
 
 You can turn off magic arguments by passing ``capture_args=False`` to
-:class:`~workflow.workflow.Workflow` on instantiation, or call the corresponding
-methods of :class:`~workflow.workflow.Workflow` directly, perhaps assigning your
-own keywords within your Workflow:
+:class:`~workflow.workflow.Workflow` on instantiation, or call the corresponding methods of :class:`~workflow.workflow.Workflow` directly,
+perhaps assigning your own keywords within your Workflow:
 
+- :meth:`~workflow.workflow.Workflow.open_help`
 - :meth:`~workflow.workflow.Workflow.open_log`
 - :meth:`~workflow.workflow.Workflow.open_cachedir`
 - :meth:`~workflow.workflow.Workflow.open_datadir`
@@ -65,3 +70,40 @@ own keywords within your Workflow:
 - :meth:`~workflow.workflow.Workflow.reset` (a shortcut to call the three previous ``clear_*`` methods)
 - :meth:`~workflow.workflow.Workflow.check_update`
 - :meth:`~workflow.workflow.Workflow.start_update`
+
+.. _custom-magic:
+
+Customising magic arguments
+---------------------------
+
+The default prefix for magic arguments (``workflow:``) is contained in the
+:attr:`~workflow.workflow.Workflow.magic_prefix` attribute of
+:class:`~workflow.workflow.Workflow`. If you want to change it to, say,
+``wf:`` (which will become the default in v2 of Alfred-Workflow), simply
+reassign it::
+
+	wf.magic_prefix = 'wf:'
+
+The magic arguments are defined in the :attr:`Workflow.magic_arguments <workflow.workflow.Workflow.magic_arguments>` dictionary.
+The dictionary keys are the keywords for the arguments (without the
+prefix) and the values are functions that should be called when the magic
+argument is entered. You can show a message in Alfred by returning a
+``unicode`` string from the function.
+
+To add a new magic argument that opens the workflow's settings file, you
+could do:
+
+.. code-block:: python
+	:linenos:
+
+	wf = Workflow()
+	wf.magic_prefix = 'wf:'  # Change prefix to `wf:`
+
+	def opensettings():
+		subprocess.call(['open', wf.settings_path])
+		return 'Opening workflow settings...'
+
+	wf.magic_arguments['settings'] = opensettings
+
+Now entering ``wf:settings`` as your workflow's query in Alfred will
+open ``settings.json`` in the default application.