Add cwd post-write hook option

Fixes #822

Implements a `.cwd` suboption for post-write hooks.

For example, one 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
pre-commit.cwd = %(here)s
```

This feature is illustrated by the last line above.

### Description

* Improve the names of some variables recently created in #820 in order to make the code more readable.
* Add `cwd` as an option which is passed directly into `subprocess.run()`
* Add a brief description to the documentation, together with an example with `pre-commit`.
<!-- Describe your changes in detail -->

### 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:

A new feature implementation

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

**Help requested:** I can't think of any simple way to write a test. Does anyone have a suggestion???

Closes: #823
Pull-request: https://github.com/sqlalchemy/alembic/pull/823
Pull-request-sha: 9a694a7fdfc55160d1e124f6119a7a5677ce019a

Change-Id: Iacbb06d52acc362588cff2cdfec442393be8594a

1 files changed, 13 insertions, 10 deletions

diff --git a/alembic/script/write_hooks.py b/alembic/script/write_hooks.py
index 27e9a48..133bf04 100644
--- a/alembic/script/write_hooks.py
+++ b/alembic/script/write_hooks.py
@@ -88,7 +88,7 @@ def _run_hooks(path, hook_config):
             )
 
 
-def _parse_options(options_str, path):
+def _parse_cmdline_options(cmdline_options_str, path):
     """Parse options from a string into a list.
 
     Also substitutes the revision script token with the actual filename of
@@ -97,13 +97,14 @@ def _parse_options(options_str, path):
     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
+    if REVISION_SCRIPT_TOKEN not in cmdline_options_str:
+        cmdline_options_str = REVISION_SCRIPT_TOKEN + " " + cmdline_options_str
+    cmdline_options_list = shlex.split(cmdline_options_str)
+    cmdline_options_list = [
+        option.replace(REVISION_SCRIPT_TOKEN, path)
+        for option in cmdline_options_list
     ]
-    return options_list
+    return cmdline_options_list
 
 
 @register("console_scripts")
@@ -122,8 +123,9 @@ def console_scripts(path, options):
         )
     iter_ = pkg_resources.iter_entry_points("console_scripts", entrypoint_name)
     impl = next(iter_)
-    options_str = options.get("options", "")
-    options_list = _parse_options(options_str, path)
+    cwd = options.get("cwd", None)
+    cmdline_options_str = options.get("options", "")
+    cmdline_options_list = _parse_cmdline_options(cmdline_options_str, path)
 
     subprocess.run(
         [
@@ -132,5 +134,6 @@ def console_scripts(path, options):
             "import %s; %s()"
             % (impl.module_name, ".".join((impl.module_name,) + impl.attrs)),
         ]
-        + options_list
+        + cmdline_options_list,
+        cwd=cwd,
     )