sqlpush 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

sqlpush/cli.py

@@ -42,6 +42,10 @@ ExcludeOpt = Annotated[list[str] | None, typer.Option("--exclude")]
 # exempts typer.Option for non-Path annotations. None default: lets the
 # verb tell "user passed --dir" apart from "use hook/default" resolution.
 DirOpt = Annotated[Path | None, typer.Option("--dir")]
+# Hook-location override, on EVERY verb (hook loading is shared
+# machinery like --dsn): flag > $SQLPUSH_HOOK > candidates, and an
+# explicit path that does not exist fails loud in the loader.
+HookOpt = Annotated[Path | None, typer.Option("--hook")]
 DEFAULT_CHAIN_DIR = Path("migrations/versions")
 
 
@@ -119,8 +123,9 @@ def diff(
     quiet: bool = typer.Option(False, "--quiet"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
-    hook = load_project_hook()
+    hook = load_project_hook(hook_path)
     md = _metadata(metadata_spec, hook)
     engine = _engine(dsn, hook)
     try:
@@ -145,8 +150,9 @@ def check(
     quiet: bool = typer.Option(False, "--quiet"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
-    hook = load_project_hook()
+    hook = load_project_hook(hook_path)
     md = _metadata(metadata_spec, hook)
     engine = _engine(dsn, hook)
     try:
@@ -187,8 +193,9 @@ def push(
     quiet: bool = typer.Option(False, "--quiet"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
-    hook = load_project_hook()
+    hook = load_project_hook(hook_path)
     md = _metadata(metadata_spec, hook)
     engine = _engine(dsn, hook)
     try:
@@ -264,9 +271,10 @@ def revision(
     no_concurrently: bool = typer.Option(False, "--no-concurrently"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
+    hook_path: HookOpt = None,
 ):
     """Generate the next migration file from models vs the reference DB."""
-    hook = load_project_hook()
+    hook = load_project_hook(hook_path)
     md = _metadata(metadata_spec, hook)
     # --ref-dsn: flag > hook.get_dsn(); NO DATABASE_URL fallback (the
     # reference DB is a different database from the push target —
@@ -305,9 +313,10 @@ def migrate(
     lock_timeout: float = typer.Option(5.0, "--lock-timeout"),
     statement_timeout: float | None = typer.Option(None, "--statement-timeout"),
     out_dir: DirOpt = None,
+    hook_path: HookOpt = None,
 ):
     """Replay pending migration files (gates + checksum bookkeeping)."""
-    hook = load_project_hook()
+    hook = load_project_hook(hook_path)
     engine = _engine(dsn, hook)
     try:
         report = api.migrate(
@@ -336,9 +345,10 @@ def stamp(
     dsn: str | None = typer.Option(None),
     force: bool = typer.Option(False, "--force"),
     out_dir: DirOpt = None,
+    hook_path: HookOpt = None,
 ):
     """Adopt an existing DB: register chain files without executing SQL."""
-    hook = load_project_hook()
+    hook = load_project_hook(hook_path)
     engine = _engine(dsn, hook)
     try:
         report = api.stamp(engine, chain_dir=_resolve_dir(out_dir, hook), force=force)

sqlpush/hook.py

@@ -1,20 +1,30 @@
 # src/sqlpush/hook.py
-"""Project hook: ``sqlpush.py`` in the CWD.
-
-The alembic ``env.py`` / pytest ``conftest.py`` pattern: when a
-``sqlpush.py`` exists next to where the user runs the CLI, it becomes
-the source of defaults for metadata, DSN and chain dir. Explicit flags
-always win (flag > hook > env/default); without the hook every verb
-behaves exactly as before.
+"""Project hook: ``migrations/sqlpush.py`` first, then ``sqlpush.py``.
+
+The alembic ``env.py`` / pytest ``conftest.py`` pattern: a hook file
+next to where the user runs the CLI becomes the source of defaults for
+metadata, DSN and chain dir. Explicit flags always win (flag > hook >
+env/default); without the hook every verb behaves exactly as before.
+
+Discovery checks ``migrations/sqlpush.py`` first (the preferred
+location — it lives next to the chain, no root clutter) and falls
+back to the repo-root ``sqlpush.py`` (backwards compat); first match
+wins. An explicit override — the ``--hook`` flag or the
+``SQLPUSH_HOOK`` env var (the alembic ``-c`` equivalent) — names any
+file instead, and is fail-loud: a path that does not exist raises a
+:class:`HookError` naming that path, never a silent fallback to
+the candidates. Precedence: flag > env > candidates.
 
 Loading is BY PATH (``spec_from_file_location``), never by module
 name: a file named ``sqlpush.py`` in the CWD would shadow the
 installed package if the CWD came first on ``sys.path`` — so the CWD
-is APPENDED (never ``insert(0)``), guaranteeing the package wins for
+is APPENDED (never ``insert(0)``), and always the CWD, never the
+loaded file's own directory (the append exists so the consumer's
+package imports resolve). This guarantees the package wins for
 normal imports while the hook itself is only ever loaded explicitly.
 
 Only typed :class:`SqlpushError`-family errors escape this module,
-always naming the file and the member involved.
+always naming the file that actually loaded and the member involved.
 """
 
 from __future__ import annotations
@@ -28,54 +38,107 @@ from types import ModuleType
 from sqlpush.types import SqlpushError
 
 HOOK_FILENAME = "sqlpush.py"
+HOOK_ENV_VAR = "SQLPUSH_HOOK"
+# first match wins: migrations/ (next to the chain) preferred, the
+# repo root kept as the backwards-compat fallback
+CANDIDATES = (Path("migrations") / HOOK_FILENAME, Path(HOOK_FILENAME))
+# resolved loaded path -> the spelling it was named with (candidate or
+# override path): _hook_label uses it so override-loaded hooks error in
+# the GIVEN spelling, matching the candidate message contract
+_LOADED_LABELS: dict[Path, str] = {}
 
 
 class HookError(SqlpushError):
     """The project hook is broken or incomplete — names file + member."""
 
 
-def load_project_hook() -> ModuleType | None:
-    """Load ``./sqlpush.py`` by path if present; ``None`` when absent.
+def load_project_hook(hook_path: Path | str | None = None) -> ModuleType | None:
+    """Load the project hook; ``None`` when nothing resolves.
 
-    On success the CWD is appended to ``sys.path`` (never inserted at
-    the front — see the module docstring for the shadowing rationale).
-    Any import-time failure is re-typed as :class:`HookError`.
+    Precedence: ``hook_path`` (the ``--hook`` flag) > ``$SQLPUSH_HOOK``
+    > the first existing candidate (``migrations/sqlpush.py``, then the
+    repo root). An explicit path (flag or env) is fail-loud: when it
+    does not exist a :class:`HookError` names that path — an
+    explicit instruction must not silently fall back to discovery.
+    Relative paths resolve against the CWD. On success the CWD is
+    appended to ``sys.path`` (never inserted at the front, and never
+    the loaded file's own directory — see the module docstring). Any
+    import-time failure is re-typed as :class:`HookError` naming the
+    file that failed, in the spelling it was named with.
     """
-    path = Path.cwd() / HOOK_FILENAME
-    if not path.is_file():
+    explicit: Path | None = None
+    if hook_path is not None:
+        explicit = Path(hook_path)
+    else:
+        env_value = os.environ.get(HOOK_ENV_VAR)
+        if env_value:  # empty string ≡ unset
+            explicit = Path(env_value)
+    if explicit is not None:
+        if not explicit.is_file():
+            raise HookError(f"{explicit.as_posix()}: file not found")
+        return _load_hook_file(explicit)
+    hook_file = next((p for p in CANDIDATES if p.is_file()), None)
+    if hook_file is None:
         return None
+    return _load_hook_file(hook_file)
+
+
+def _load_hook_file(hook_file: Path) -> ModuleType:
     sys.path.append(os.getcwd())
-    spec = importlib.util.spec_from_file_location("sqlpush_project_hook", path)
+    spec = importlib.util.spec_from_file_location("sqlpush_project_hook", hook_file)
     if spec is None or spec.loader is None:
-        raise HookError(f"{HOOK_FILENAME}: cannot load (invalid module spec)")
+        raise HookError(f"{hook_file.as_posix()}: cannot load (invalid module spec)")
     module = importlib.util.module_from_spec(spec)
+    _LOADED_LABELS[hook_file.resolve()] = hook_file.as_posix()
     try:
         spec.loader.exec_module(module)
     except Exception as exc:
-        raise HookError(f"{HOOK_FILENAME}: import raised: {exc}") from exc
+        raise HookError(f"{hook_file.as_posix()}: import raised: {exc}") from exc
     return module
 
 
+def _hook_label(hook: ModuleType) -> str:
+    """The spelling the loaded hook file was named with (posix, portable).
+
+    Errors must name the file that actually loaded: map the loaded
+    module's ``__file__`` back to its load-time spelling (candidate or
+    override path); unknown provenance degrades to the bare filename.
+    """
+    loaded_file = getattr(hook, "__file__", None)
+    if not loaded_file:
+        return HOOK_FILENAME
+    loaded = Path(loaded_file).resolve()
+    label = _LOADED_LABELS.get(loaded)
+    if label is not None:
+        return label
+    for candidate in CANDIDATES:
+        if (Path.cwd() / candidate).resolve() == loaded:
+            return candidate.as_posix()
+    return HOOK_FILENAME
+
+
 def hook_dsn(hook: ModuleType) -> str:
     """Call ``get_dsn()`` LAZILY — only when a verb actually needs it."""
+    label = _hook_label(hook)
     getter = getattr(hook, "get_dsn", None)
     if getter is None:
-        raise HookError(f"{HOOK_FILENAME}: missing get_dsn()")
+        raise HookError(f"{label}: missing get_dsn()")
     try:
         return getter()
     except Exception as exc:
-        raise HookError(f"{HOOK_FILENAME}: get_dsn() raised: {exc}") from exc
+        raise HookError(f"{label}: get_dsn() raised: {exc}") from exc
 
 
 def hook_metadata(hook: ModuleType):
     """Call ``get_metadata()`` LAZILY — returns the populated MetaData object."""
+    label = _hook_label(hook)
     getter = getattr(hook, "get_metadata", None)
     if getter is None:
-        raise HookError(f"{HOOK_FILENAME}: missing get_metadata()")
+        raise HookError(f"{label}: missing get_metadata()")
     try:
         return getter()
     except Exception as exc:
-        raise HookError(f"{HOOK_FILENAME}: get_metadata() raised: {exc}") from exc
+        raise HookError(f"{label}: get_metadata() raised: {exc}") from exc
 
 
 def hook_chain_dir(hook: ModuleType | None, default: str) -> str:

{sqlpush-0.6.0.dist-info → sqlpush-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlpush
-Version: 0.6.0
+Version: 0.7.0
 Summary: Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models
 Keywords: sqlalchemy,sqlmodel,fastapi,alembic,postgresql,timescaledb,prisma,schema,migrations,database,drift,cli
 Author: Juan Miguel Contreras
@@ -198,12 +198,17 @@ the workflows.
 
 ## Project hook
 
-Drop a `sqlpush.py` in your repo root (the alembic `env.py` /
-pytest `conftest.py` pattern) and the CLI stops needing flags,
-specs and env vars:
+Drop a `sqlpush.py` where sqlpush can find it (the alembic `env.py` /
+pytest `conftest.py` pattern) and the CLI stops needing flags, specs
+and env vars. Two discovered locations, first match wins — or name
+any file explicitly with `--hook`/`$SQLPUSH_HOOK`:
+
+1. `migrations/sqlpush.py` — preferred: it lives next to the chain,
+   no repo-root clutter.
+2. `sqlpush.py` — repo root, kept as the backwards-compat fallback.
 
 ```python
-# sqlpush.py — in your repo root
+# migrations/sqlpush.py — the preferred location
 def get_metadata():  # REQUIRED for diff/check/push/revision
     from myapp.models import metadata
 
@@ -223,23 +228,33 @@ With that file in place, `uv run sqlpush revision -m "change"` just
 works: no `--dsn`, no `module:attribute`, no credentials on the
 command line, no PYTHONPATH. Inputs resolve with a fixed precedence:
 
-| input | explicit flag | `sqlpush.py` | fallback |
+| input | explicit flag | hook | fallback |
 | --- | --- | --- | --- |
 | `--dsn` / `--ref-dsn` | wins | `get_dsn()` | `$DATABASE_URL`, only without a hook and never for `--ref-dsn` |
 | `module:attribute` (diff/check/push/revision) | wins | `get_metadata()` | usage error |
 | `--dir` (revision/migrate/stamp) | wins | `CHAIN_DIR` | `migrations/versions` |
+| which file is the hook | `--hook PATH` | — | `$SQLPUSH_HOOK`, else first match: `migrations/sqlpush.py`, then root `sqlpush.py` |
+
+The hook's location is the alembic `-c` equivalent: `--hook` >
+`$SQLPUSH_HOOK` > discovery, any location you want (relative paths
+resolve against the CWD) — and the explicit forms fail loud, with an
+error naming that path (`custom/hook.py: file not found`)
+instead of falling back to the discovered candidates.
 
 A hook that is missing a member a verb needs — or whose
 `get_dsn()`/`get_metadata()` raises — fails with a typed error naming
-the file and the member (`sqlpush.py: missing get_dsn()`), never a
-traceback. Without a `sqlpush.py`, every verb behaves exactly as
-before.
+the file that actually loaded and the member
+(`migrations/sqlpush.py: missing get_dsn()`), never a traceback.
+Without a hook, every verb behaves exactly as before.
 
 One deliberate detail: on discovering the hook, sqlpush **appends**
-your CWD to `sys.path` instead of prepending it. A file named
+your CWD to `sys.path` instead of prepending it — whatever location
+the hook loaded from, never the hook's own directory. A root
 `sqlpush.py` would otherwise shadow the installed package the moment
 you ran the CLI from your repo root; appending guarantees the real
-package always wins, and the hook is loaded by path only.
+package always wins, and the hook itself is loaded by path only (the
+`migrations/` candidate has no shadowing concern but loads the same
+way).
 
 ## Exit codes
 
@@ -272,8 +287,10 @@ The knobs, per verb:
 | `migrate` | `--allow-destructive` `--advisory-wait` `--lock-timeout` `--statement-timeout` `--dir` |
 | `stamp` | `--force` `--dir` |
 
-Every verb except `revision` takes `--dsn` (or `$DATABASE_URL`, or
-the project hook's `get_dsn()`). `revision` takes `--ref-dsn` — or
+Every verb takes `--hook PATH` (or `$SQLPUSH_HOOK`) to name the hook
+file explicitly. Every verb except `revision` takes `--dsn` (or
+`$DATABASE_URL`, or the project hook's `get_dsn()`). `revision`
+takes `--ref-dsn` — or
 the hook — with no env fallback: the reference DB is a different
 database from the push target. `diff`, `check`,
 `push` and `revision` also take repeatable `--schema` / `--exclude`.

{sqlpush-0.6.0.dist-info → sqlpush-0.7.0.dist-info}/RECORD

@@ -6,16 +6,16 @@ sqlpush/apply/executor.py,sha256=qHvfxB1sWQAQ0oMPDGuEr-HRaJwOYoVSB_s-7x-CZTc,100
 sqlpush/chain/__init__.py,sha256=AJ96P3I63mX6-uMuK0paCpKtaRexufnCqjUuElbyAsM,293
 sqlpush/chain/format.py,sha256=uj0iMQfFWa9HpKhrokfJu_5B_FesiD4qCZxAGDJ3bfQ,4938
 sqlpush/chain/migrate.py,sha256=P2grgrg8dkLJCBhL6CzNwa4xG8-VuFLqgN7XuvjFhwQ,18575
-sqlpush/cli.py,sha256=A49c6HxDv6-8I9cX3jT5ujqmBqD-keUPpcOSPExw48o,12860
+sqlpush/cli.py,sha256=sF0F0xNTUzdXRPLB09EDHgNJUqHkTMgCbv_vSvSHgFk,13350
 sqlpush/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sqlpush/core/classify.py,sha256=xjBFIPAV8lxMsZZRiOQ1Yxlpgz4r-ZpCtnNXA4KAw0o,1290
 sqlpush/core/diff.py,sha256=OkH0fLl9NLOyWFnefknvBK8SWeN6bnJz4kQJfK3-wFA,26552
 sqlpush/core/render.py,sha256=9SNEyHOGmMxKUfIjvo3x0MNVQ6N2o2fl3noWT1EWO3M,609
 sqlpush/directives/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sqlpush/directives/timescale.py,sha256=W_Cd_stdhKZlzlMum7Bdzq99VfXOulYxq0B-sukz-xE,2645
-sqlpush/hook.py,sha256=RRGm0-ODh4YqsG6s-uvaCBIyJ6HvDUcBgHD-OxlQcQQ,3076
+sqlpush/hook.py,sha256=t2qOLt4m8JjTDEIO7eJCusvdhLx3u8ztvtO8705yb5Q,6068
 sqlpush/types.py,sha256=hXetdVqMzYcBQi0M_x3qmCIOa3QzhuwxYNJkZRWz4qM,3280
-sqlpush-0.6.0.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
-sqlpush-0.6.0.dist-info/entry_points.txt,sha256=VYha3PJSvklRgpcDAZYJdE66EXM79MSKQf0z8igyAOI,46
-sqlpush-0.6.0.dist-info/METADATA,sha256=bO1edF0e_VA7G_Ya6sXboPndA4cYrY-5JpAr3MD9VyA,14317
-sqlpush-0.6.0.dist-info/RECORD,,
+sqlpush-0.7.0.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
+sqlpush-0.7.0.dist-info/entry_points.txt,sha256=VYha3PJSvklRgpcDAZYJdE66EXM79MSKQf0z8igyAOI,46
+sqlpush-0.7.0.dist-info/METADATA,sha256=v7OfjIX8LydcDbKIuF8T4Fb4hnzRLuYBhz7s_MSIMUE,15317
+sqlpush-0.7.0.dist-info/RECORD,,