Add "module" post-write hook

[RazerM]

Describe the use case

The exec hook has a downside compared to the console_scripts hook — I have to either give a path to my virtual environment, or rely on it being found on PATH.

In contrast, the console_scripts hook doesn't need to do this because it uses sys.executable to find the installed package – whether that's black or something else.

All formatters/linters I'm aware of can be run using python -m <module>, which is what the new hook would do using sys.executable.

Databases / Backends / Drivers targeted

N/A

Example Use

hooks = ruff
ruff.type = module
ruff.module = ruff
ruff.options = format REVISION_SCRIPT_FILENAME

hooks = black
black.type = module
black.module = black
black.options = REVISION_SCRIPT_FILENAME

Additional context

PR incoming

Have a nice day!

[zzzeek]

Mmmmm, not enthusiastic yet. what's wrong with console_scripts? That's a well published API hook, whereas "module" is just something arbitrary.

if this rather large amount of code is just for ruff, I'm -1 on that. Why can't ruff add a console_scripts entrypoint?

[RazerM]

That's a well published API hook, whereas "module" is just something arbitrary.

I don't think using python -m <module> is "just something arbitrary". It's part of the language and well supported by tools.

Why can't ruff add a console_scripts entrypoint?

console_scripts tells the installer (pip/uv) to create an executable Python script at e.g. .venv/bin/black which imports the function specified by black and executes it. ruff can't do that because .venv/bin/ruff is already a binary, it doesn't need a script to be created.

if this [...] is just for ruff, I'm -1 on that.

Unlike exec, it's the only way I can make sure alembic is invoking the installed ruff version that doesn't hardcode a $PWD/.venv.

So I primarily want it for ruff, yes, but it works with any package that can be invoked with -m: black, ruff, isort, zimports, et cetera. As a user you don't really know whether a package's executable script or binary came from console_scripts or not.

I actually think it could make the documentation clearer if all the examples used module and then there's no difference between the examples for black and ruff, but it's not really my goal to advocate for that change.

rather large amount of code

I don't think it's that much code? Here's the diff between the console_scripts hook and the module hook:

diff --git i/alembic/script/write_hooks.py w/alembic/script/write_hooks.py
index cf96e91d..18dfcc5a 100644
--- i/alembic/script/write_hooks.py
+++ w/alembic/script/write_hooks.py
@@ -113,25 +113,21 @@ def _parse_cmdline_options(cmdline_options_str: str, path: str) -> List[str]:
     return cmdline_options_list
 
 
-@register("console_scripts")
-def console_scripts(
+@register("module")
+def module(
     path: str, options: dict, ignore_output: bool = False
 ) -> None:
     try:
-        entrypoint_name = options["entrypoint"]
+        module_name = options["module"]
     except KeyError as ke:
         raise util.CommandError(
-            f"Key {options['_hook_name']}.entrypoint is required for post "
+            f"Key {options['_hook_name']}.module is required for post "
             f"write hook {options['_hook_name']!r}"
         ) from ke
-    for entry in compat.importlib_metadata_get("console_scripts"):
-        if entry.name == entrypoint_name:
-            impl: Any = entry
-            break
-    else:
-        raise util.CommandError(
-            f"Could not find entrypoint console_scripts.{entrypoint_name}"
-        )
+
+    if importlib.util.find_spec(module_name) is None:
+        raise util.CommandError(f"Could not find module {module_name}")
+
     cwd: Optional[str] = options.get("cwd", None)
     cmdline_options_str = options.get("options", "")
     cmdline_options_list = _parse_cmdline_options(cmdline_options_str, path)
@@ -143,8 +139,8 @@ def console_scripts(
     subprocess.run(
         [
             sys.executable,
-            "-c",
-            f"import {impl.module}; {impl.module}.{impl.attr}()",
+            "-m",
+            module_name,
         ]
         + cmdline_options_list,
         cwd=cwd,

The rest is tests which I based on the console_scripts tests.

[sqla-tester]

Frazer McLean has proposed a fix for this issue in the main branch:

Add "module" post-write hook https://gerrit.sqlalchemy.org/c/sqlalchemy/alembic/+/6021