Add REVISION_SCRIPT_FILENAME token for post_write_hooks options

I include a token called `REVISION_SCRIPT_FILENAME` which can be used in the `options` setting of a post-write hook. This token is replaced by the filename of the revision script, allowing the filename to be passed to the post-write hook in a flexible manner. Thus I can do:

```ini
[post_write_hooks]
hooks = pre-commit
pre-commit.type = console_scripts
pre-commit.entrypoint = pre-commit
pre-commit.options = run --files REVISION_SCRIPT_FILENAME
```

Note that the existing behavior is to prepend `REVISION_SCRIPT_FILENAME` to the argument list. In order to preserve backwards compatibility, this is done when `REVISION_SCRIPT_FILENAME` is not present.

### Description
* Implement the `REVISION_SCRIPT_FILENAME` token.
* Switch from `str.split()` to `shlex.split()` for robust command line argument processing.
* Insert `REVISION_SCRIPT_FILENAME` in appropriate locations in the docs and templates.
* Properly document that `REVISION_SCRIPT_FILENAME` is prepended instead of appended to the argument list.
* Refactored existing "test of `black` as a post-write hook" in order to avoid code duplication.
* Add a test for `REVISION_SCRIPT_FILENAME` and shlex.

### Checklist
<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)

-->

This pull request is:

- [X] A new feature implementation
	- please include the issue number, and create an issue if none exists, which must
	  include a complete example of how the feature would look.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.

Fixes issue #819

Closes: #820
Pull-request: https://github.com/sqlalchemy/alembic/pull/820
Pull-request-sha: 73dd0a4d60758a06551a0aff47b9723b0345d74a

Change-Id: Ibfc677d59086703872d7cfd5c2da32bd0220a25f

1 files changed, 25 insertions, 3 deletions

diff --git a/alembic/script/write_hooks.py b/alembic/script/write_hooks.py
index d6d1d38..27e9a48 100644
--- a/alembic/script/write_hooks.py
+++ b/alembic/script/write_hooks.py
@@ -1,3 +1,4 @@
+import shlex
 import subprocess
 import sys
 
@@ -5,6 +6,8 @@ from .. import util
 from ..util import compat
 
 
+REVISION_SCRIPT_TOKEN = "REVISION_SCRIPT_FILENAME"
+
 _registry = {}
 
 
@@ -85,6 +88,24 @@ def _run_hooks(path, hook_config):
             )
 
 
+def _parse_options(options_str, path):
+    """Parse options from a string into a list.
+
+    Also substitutes the revision script token with the actual filename of
+    the revision script.
+
+    If the revision script token doesn't occur in the options string, it is
+    automatically prepended.
+    """
+    if REVISION_SCRIPT_TOKEN not in options_str:
+        options_str = REVISION_SCRIPT_TOKEN + " " + options_str
+    options_list = shlex.split(options_str)
+    options_list = [
+        option.replace(REVISION_SCRIPT_TOKEN, path) for option in options_list
+    ]
+    return options_list
+
+
 @register("console_scripts")
 def console_scripts(path, options):
     import pkg_resources
@@ -101,14 +122,15 @@ def console_scripts(path, options):
         )
     iter_ = pkg_resources.iter_entry_points("console_scripts", entrypoint_name)
     impl = next(iter_)
-    options = options.get("options", "")
+    options_str = options.get("options", "")
+    options_list = _parse_options(options_str, path)
+
     subprocess.run(
         [
             sys.executable,
             "-c",
             "import %s; %s()"
             % (impl.module_name, ".".join((impl.module_name,) + impl.attrs)),
-            path,
         ]
-        + options.split()
+        + options_list
     )