sqlpush 0.6.0__tar.gz → 0.7.0__tar.gz

{sqlpush-0.6.0 → sqlpush-0.7.0}/PKG-INFO

@@ -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 → sqlpush-0.7.0}/README.md

@@ -169,12 +169,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
 
@@ -194,23 +199,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
 
@@ -243,8 +258,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 → sqlpush-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.6.0"
+version = "0.7.0"
 description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
 readme = "README.md"
 requires-python = ">=3.10"

{sqlpush-0.6.0 → sqlpush-0.7.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.6.0"
+version = "0.7.0"
 description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
 readme = "README.md"
 authors = [

{sqlpush-0.6.0 → sqlpush-0.7.0}/src/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-0.7.0/src/sqlpush/hook.py

@@ -0,0 +1,147 @@
+# src/sqlpush/hook.py
+"""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)``), 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 that actually loaded and the member involved.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+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(hook_path: Path | str | None = None) -> ModuleType | None:
+    """Load the project hook; ``None`` when nothing resolves.
+
+    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.
+    """
+    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", hook_file)
+    if spec is None or spec.loader is None:
+        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_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"{label}: missing get_dsn()")
+    try:
+        return getter()
+    except Exception as 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"{label}: missing get_metadata()")
+    try:
+        return getter()
+    except Exception as exc:
+        raise HookError(f"{label}: get_metadata() raised: {exc}") from exc
+
+
+def hook_chain_dir(hook: ModuleType | None, default: str) -> str:
+    """Read ``CHAIN_DIR`` as a module attribute; ``default`` when unset."""
+    value = getattr(hook, "CHAIN_DIR", None) if hook is not None else None
+    return default if value is None else value

sqlpush-0.6.0/src/sqlpush/hook.py

@@ -1,84 +0,0 @@
-# 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.
-
-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
-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.
-"""
-
-from __future__ import annotations
-
-import importlib.util
-import os
-import sys
-from pathlib import Path
-from types import ModuleType
-
-from sqlpush.types import SqlpushError
-
-HOOK_FILENAME = "sqlpush.py"
-
-
-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.
-
-    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`.
-    """
-    path = Path.cwd() / HOOK_FILENAME
-    if not path.is_file():
-        return None
-    sys.path.append(os.getcwd())
-    spec = importlib.util.spec_from_file_location("sqlpush_project_hook", path)
-    if spec is None or spec.loader is None:
-        raise HookError(f"{HOOK_FILENAME}: cannot load (invalid module spec)")
-    module = importlib.util.module_from_spec(spec)
-    try:
-        spec.loader.exec_module(module)
-    except Exception as exc:
-        raise HookError(f"{HOOK_FILENAME}: import raised: {exc}") from exc
-    return module
-
-
-def hook_dsn(hook: ModuleType) -> str:
-    """Call ``get_dsn()`` LAZILY — only when a verb actually needs it."""
-    getter = getattr(hook, "get_dsn", None)
-    if getter is None:
-        raise HookError(f"{HOOK_FILENAME}: missing get_dsn()")
-    try:
-        return getter()
-    except Exception as exc:
-        raise HookError(f"{HOOK_FILENAME}: get_dsn() raised: {exc}") from exc
-
-
-def hook_metadata(hook: ModuleType):
-    """Call ``get_metadata()`` LAZILY — returns the populated MetaData object."""
-    getter = getattr(hook, "get_metadata", None)
-    if getter is None:
-        raise HookError(f"{HOOK_FILENAME}: missing get_metadata()")
-    try:
-        return getter()
-    except Exception as exc:
-        raise HookError(f"{HOOK_FILENAME}: get_metadata() raised: {exc}") from exc
-
-
-def hook_chain_dir(hook: ModuleType | None, default: str) -> str:
-    """Read ``CHAIN_DIR`` as a module attribute; ``default`` when unset."""
-    value = getattr(hook, "CHAIN_DIR", None) if hook is not None else None
-    return default if value is None else value