dbression 0.1.0__py3-none-any.whl

dbression/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dbression/cli.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from dbression import __version__
+from dbression.parser import parse_suite
+from dbression.parser.markdown_writer import page_to_markdown
+from dbression.parser.wiki import parse_wiki
+from dbression.report import print_suite_result, write_json_report, write_junit_xml
+from dbression.runner import TagFilter, build_engine_for_suite, run_suite
+
+app = typer.Typer(
+    name="dbression",
+    help="Modern Python port of DBFit — regression tests for database schemas and business logic.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+console = Console()
+
+
+@app.callback()
+def _main_callback() -> None:
+    """Force multi-command mode so `dbression <subcommand>` works."""
+
+
+@app.command()
+def version() -> None:
+    """Print the installed dbression version."""
+    console.print(f"dbression {__version__}")
+
+
+@app.command()
+def run(
+    path: Annotated[Path, typer.Argument(help="Path to the suite (directory containing _root.wiki)")],
+    commit_mode: Annotated[
+        str,
+        typer.Option(
+            "--commit-mode",
+            help="'test' = rollback per test (default), 'page' = commit per page (DBFit-compatible)",
+        ),
+    ] = "test",
+    verbose: Annotated[
+        bool, typer.Option("-v", "--verbose", help="Print every fixture table, not just the page line")
+    ] = False,
+    tag: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--tag",
+            help="Only run pages carrying this tag (front-matter `Suites:`); may be passed multiple times",
+        ),
+    ] = None,
+    skip_tag: Annotated[
+        list[str] | None,
+        typer.Option("--skip-tag", help="Skip pages carrying this tag; may be passed multiple times"),
+    ] = None,
+    junit_xml: Annotated[
+        Path | None,
+        typer.Option("--junit-xml", help="Write a JUnit-XML report to this path (CI: Bitbucket/Jenkins)"),
+    ] = None,
+    json_report: Annotated[
+        Path | None,
+        typer.Option("--json", help="Write a JSON report to this path (LLM / tooling)"),
+    ] = None,
+) -> None:
+    """Run a dbression suite and produce pytest-style reporting."""
+    if not path.is_dir():
+        console.print(f"[red]Not a directory:[/red] {path}")
+        raise typer.Exit(2)
+    if commit_mode not in ("test", "page"):
+        console.print(
+            f"[red]Invalid commit-mode: {commit_mode!r} (allowed: test, page)[/red]"
+        )
+        raise typer.Exit(2)
+
+    tag_filter = TagFilter(only=tuple(tag or ()), skip=tuple(skip_tag or ()))
+
+    suite = parse_suite(path)
+    engine = build_engine_for_suite(suite)
+    console.print(
+        f"dbression {__version__} — Suite: [bold]{suite.name}[/bold] @ "
+        f"{engine.url.render_as_string(hide_password=True)}\n"
+    )
+    try:
+        result = run_suite(suite, engine, commit_mode=commit_mode, tag_filter=tag_filter)  # type: ignore[arg-type]
+    finally:
+        engine.dispose()
+    print_suite_result(result, console, verbose=verbose)
+
+    if junit_xml is not None:
+        write_junit_xml(result, junit_xml)
+        console.print(f"[dim]JUnit-XML: {junit_xml}[/dim]")
+    if json_report is not None:
+        write_json_report(result, json_report)
+        console.print(f"[dim]JSON report: {json_report}[/dim]")
+
+    if result.error or result.failed_count > 0:
+        raise typer.Exit(1)
+
+
+@app.command()
+def convert(
+    path: Annotated[Path, typer.Argument(help="Path to a .wiki file OR a directory")],
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "-o",
+            "--output",
+            help="Destination path (file or directory); default: in-place next to the source",
+        ),
+    ] = None,
+    force: Annotated[bool, typer.Option("-f", "--force", help="Overwrite existing .test.md")] = False,
+) -> None:
+    """Convert ``.wiki`` files (DBFit format) to ``.test.md`` (dbression's own format)."""
+    if not path.exists():
+        console.print(f"[red]Path does not exist:[/red] {path}")
+        raise typer.Exit(2)
+
+    wiki_files: list[Path] = []
+    if path.is_file():
+        if path.suffix != ".wiki":
+            console.print(f"[red]Expected a .wiki file, got:[/red] {path}")
+            raise typer.Exit(2)
+        wiki_files.append(path)
+    else:
+        wiki_files = sorted(path.rglob("*.wiki"))
+        if not wiki_files:
+            console.print(f"[yellow]No .wiki files found under[/yellow] {path}")
+            raise typer.Exit(0)
+
+    written = 0
+    skipped = 0
+    for wf in wiki_files:
+        target = _convert_target(wf, output, single_input=path.is_file())
+        if target.exists() and not force:
+            console.print(f"[yellow]⏭  exists, use --force to overwrite:[/yellow] {target}")
+            skipped += 1
+            continue
+        page = parse_wiki(wf)
+        md = page_to_markdown(page)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(md, encoding="utf-8")
+        console.print(f"[green]✓[/green] {wf}  →  {target}")
+        written += 1
+
+    console.print(f"\n[bold]{written} file(s) written, {skipped} skipped[/bold]")
+
+
+def _convert_target(wiki_file: Path, output: Path | None, single_input: bool) -> Path:
+    """Compute the destination path for a converted .wiki file."""
+    md_name = wiki_file.stem + ".test.md"
+    if output is None:
+        return wiki_file.parent / md_name
+    if single_input:
+        # output is either a file or a directory
+        if output.suffix == ".md" or output.name.endswith(".test.md"):
+            return output
+        return output / md_name
+    # Directory mode: output is the destination root, mirror the structure
+    return output / md_name
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

dbression/db/__init__.py

@@ -0,0 +1,12 @@
+from dbression.db.connection import ConnectionConfig, load_connection_properties, resolve_connection_file
+from dbression.db.engine import make_engine
+from dbression.db.errors import DBError, wrap_dbapi_error
+
+__all__ = [
+    "ConnectionConfig",
+    "DBError",
+    "load_connection_properties",
+    "make_engine",
+    "resolve_connection_file",
+    "wrap_dbapi_error",
+]

dbression/db/connection.py

@@ -0,0 +1,104 @@
+"""Load DBFit-compatible ``*.connection.properties`` files."""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_VAR_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def _expand_vars(value: str) -> str:
+    """Replace ``${VAR}`` placeholders with ``os.environ[VAR]``.
+
+    If a variable is missing we raise KeyError with an informative message — silently
+    inserting an empty string would just hide the misconfiguration.
+    """
+
+    def repl(m: re.Match[str]) -> str:
+        name = m.group(1)
+        try:
+            return os.environ[name]
+        except KeyError as exc:
+            raise KeyError(
+                f"connection.properties references undefined environment variable: ${{{name}}}"
+            ) from exc
+
+    return _VAR_RE.sub(repl, value)
+
+
+@dataclass(slots=True)
+class ConnectionConfig:
+    """DBFit-compatible connection parameters.
+
+    Either `connection_string` (Easy Connect / TNS) OR (`service`, `username`, `password`).
+    `username` / `password` are still populated when a `connection_string` is set —
+    the driver decides what to use.
+    """
+
+    connection_string: str | None = None
+    service: str | None = None
+    username: str | None = None
+    password: str | None = None
+    extra: dict[str, str] | None = None
+
+
+def load_connection_properties(path: Path) -> ConnectionConfig:
+    """Parse a Java-style ``.properties`` file.
+
+    Recognized keys: `connection-string`, `service`, `username`, `password`.
+    Unknown keys land in `extra`. Lines starting with `#` or `!` are comments.
+    """
+    cfg = ConnectionConfig(extra={})
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or line.startswith("!"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip().lower()
+        value = value.strip()
+        value = _expand_vars(value)
+        if key == "connection-string":
+            cfg.connection_string = value
+        elif key == "service":
+            cfg.service = value
+        elif key == "username":
+            cfg.username = value
+        elif key == "password":
+            cfg.password = value
+        else:
+            assert cfg.extra is not None
+            cfg.extra[key] = value
+    return cfg
+
+
+def resolve_connection_file(declared: str, suite_root: Path) -> Path:
+    """Find the actual connection.properties file on disk.
+
+    DBFit suites often carry absolute paths from inside the container
+    (``/dbfit/FitNesseRoot/...``). Strategy:
+
+      1. If the absolute path exists, use it.
+      2. Otherwise take the basename and look in `suite_root` and all of its ancestors up
+         to the filesystem root.
+
+    Raises FileNotFoundError if nothing matches.
+    """
+    p = Path(declared)
+    if p.is_absolute() and p.exists():
+        return p
+    basename = p.name
+    candidate = suite_root / basename
+    if candidate.exists():
+        return candidate
+    for parent in suite_root.parents:
+        candidate = parent / basename
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError(
+        f"connection.properties file not found — declared: {declared!r}, "
+        f"searched from suite root: {suite_root}"
+    )

dbression/db/engine.py

@@ -0,0 +1,131 @@
+"""Build SQLAlchemy engines from DBFit connection properties.
+
+DBFit suites carry directives of the form ``DatabaseEnvironment | <name>`` (e.g. `oracle`,
+`postgres`). This function maps that name + the loaded `ConnectionConfig` to the
+appropriate SQLAlchemy URL.
+
+For Oracle we additionally — if the environment variable ``DBRESSION_ORACLE_CLIENT_LIB_DIR``
+is set — switch to thick mode before building the engine (InstantClient is required for
+Oracle servers that reject python-oracledb's thin-mode authentication).
+"""
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any
+
+from sqlalchemy import URL, Engine, create_engine
+
+from dbression.db.connection import ConnectionConfig
+
+_THICK_INIT_LOCK = threading.Lock()
+_THICK_INITIALIZED = False
+
+
+def _maybe_init_oracle_thick() -> None:
+    global _THICK_INITIALIZED
+    if _THICK_INITIALIZED:
+        return
+    lib_dir = os.environ.get("DBRESSION_ORACLE_CLIENT_LIB_DIR")
+    if not lib_dir:
+        return
+    with _THICK_INIT_LOCK:
+        if _THICK_INITIALIZED:
+            return
+        import oracledb  # noqa: PLC0415 — keep the driver import local
+
+        oracledb.init_oracle_client(lib_dir=lib_dir)
+        _THICK_INITIALIZED = True
+
+
+_POSTGRES_ALIASES = {"postgres", "postgresql", "pg"}
+_ORACLE_ALIASES = {"oracle"}
+_MSSQL_ALIASES = {"sqlserver", "mssql", "ms-sql"}
+
+
+def make_engine(environment: str, config: ConnectionConfig) -> Engine:
+    """Build a SQLAlchemy engine. No autocommit — the runner manages transactions."""
+    env = environment.strip().lower()
+    extra: dict[str, str] = config.extra or {}
+
+    if env in _POSTGRES_ALIASES:
+        url = _build_postgres_url(config, extra)
+    elif env in _ORACLE_ALIASES:
+        _maybe_init_oracle_thick()
+        url = _build_oracle_url(config, extra)
+    elif env in _MSSQL_ALIASES:
+        url = _build_mssql_url(config, extra)
+    else:
+        raise ValueError(f"Unknown DatabaseEnvironment: {environment!r}")
+
+    # `future=True` is the default in 2.0; `pool_pre_ping` makes long-lived sessions
+    # more robust.
+    return create_engine(url, pool_pre_ping=True)
+
+
+def _build_postgres_url(cfg: ConnectionConfig, extra: dict[str, str]) -> URL | str:
+    if cfg.connection_string:
+        cs = cfg.connection_string
+        if cs.startswith("jdbc:postgresql://"):
+            cs = cs[len("jdbc:postgresql://") :]
+            return f"postgresql+psycopg://{cs}"
+        if cs.startswith("postgresql://") or cs.startswith("postgres://"):
+            scheme, _, rest = cs.partition("://")
+            return f"postgresql+psycopg://{rest}"
+        return cs  # caller's responsibility
+    host, port = _split_host_port(cfg.service)
+    return URL.create(
+        drivername="postgresql+psycopg",
+        username=cfg.username,
+        password=cfg.password,
+        host=host,
+        port=port,
+        database=extra.get("database"),
+    )
+
+
+def _build_oracle_url(cfg: ConnectionConfig, extra: dict[str, str]) -> URL | str:
+    if cfg.connection_string:
+        cs = cfg.connection_string
+        return f"oracle+oracledb://{cfg.username or ''}:{cfg.password or ''}@" + cs.replace(
+            "jdbc:oracle:thin:@", ""
+        )
+    # DBFit's `service` is Easy Connect: host:port/service_name
+    return URL.create(
+        drivername="oracle+oracledb",
+        username=cfg.username,
+        password=cfg.password,
+        host=None,
+        database=None,
+        query={"dsn": cfg.service or ""},
+    )
+
+
+def _build_mssql_url(cfg: ConnectionConfig, extra: dict[str, str]) -> URL | str:
+    """SQL Server via `pymssql` — pure-Python, no ODBC driver required."""
+    if cfg.connection_string:
+        return cfg.connection_string
+    host, port = _split_host_port(cfg.service)
+    return URL.create(
+        drivername="mssql+pymssql",
+        username=cfg.username,
+        password=cfg.password,
+        host=host,
+        port=port,
+        database=extra.get("database"),
+    )
+
+
+def _split_host_port(service: str | None) -> tuple[str | None, int | None]:
+    if not service:
+        return None, None
+    if ":" in service:
+        host, _, port_str = service.partition(":")
+        # Easy Connect: `host:port/service_name` — we ignore the service_name here for
+        # Oracle (this function is only called for PG / MSSQL).
+        port_str = port_str.split("/", 1)[0]
+        try:
+            return host, int(port_str)
+        except ValueError:
+            return service, None
+    return service, None

dbression/db/errors.py

@@ -0,0 +1,63 @@
+"""Database error representation and platform-code extraction from SQLAlchemy exceptions."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy.exc import DBAPIError
+
+
+@dataclass(slots=True)
+class DBError(Exception):
+    """Driver-agnostic database error representation.
+
+    ``code`` is a numeric platform code (Oracle: ORA-NNNNN without the prefix, as int;
+    Postgres: 0 because Postgres uses SQLSTATE instead of codes).
+    ``sqlstate`` is the 5-character SQLSTATE (native in Postgres, where available in Oracle).
+    """
+
+    code: int = 0
+    sqlstate: str = ""
+    message: str = ""
+    sql: str = ""
+    binds: dict[str, Any] | None = None
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        prefix = f"[{self.sqlstate}] " if self.sqlstate else ""
+        if self.code:
+            prefix = f"{prefix}ORA-{self.code:05d} "
+        return f"{prefix}{self.message}".strip()
+
+
+def wrap_dbapi_error(
+    exc: DBAPIError, sql: str = "", binds: dict[str, Any] | None = None
+) -> DBError:
+    """Extract platform codes from the DBAPI error wrapped by SQLAlchemy.
+
+    Works for ``oracledb.DatabaseError``, ``psycopg.Error`` and most other PEP-249 drivers.
+    """
+    orig = exc.orig
+    code = 0
+    sqlstate = ""
+    message = str(orig) if orig is not None else str(exc)
+
+    # Oracle: oracledb.DatabaseError → args[0] carries .code and .message
+    if orig is not None and hasattr(orig, "args") and orig.args:
+        inner = orig.args[0]
+        if hasattr(inner, "code") and hasattr(inner, "message"):
+            code = int(getattr(inner, "code", 0) or 0)
+            message = (getattr(inner, "message", "") or "").strip()
+
+    # Postgres (psycopg): orig.diag.sqlstate + .message_primary
+    diag = getattr(orig, "diag", None) if orig is not None else None
+    if diag is not None:
+        sqlstate = getattr(diag, "sqlstate", "") or ""
+        pg_msg = getattr(diag, "message_primary", None)
+        if pg_msg:
+            message = pg_msg.strip()
+
+    # Generic sqlstate (SQLAlchemy attaches it directly for some dialects).
+    if not sqlstate:
+        sqlstate = getattr(exc, "code", "") or ""
+
+    return DBError(code=code, sqlstate=sqlstate, message=message, sql=sql, binds=binds)

dbression/fixtures/__init__.py

@@ -0,0 +1,32 @@
+"""Fixture registry and base class."""
+from dbression.fixtures.base import (
+    Fixture,
+    FixtureContext,
+    FixtureResult,
+    REGISTRY,
+    register,
+    resolve_fixture,
+)
+
+# Importing the modules registers their fixtures via the decorator.
+from dbression.fixtures import suite_fixtures  # noqa: F401
+from dbression.fixtures import basic  # noqa: F401
+from dbression.fixtures import inspect_and_store  # noqa: F401
+
+# Load third-party fixtures via entry-points / the DBRESSION_PLUGINS env var.
+# Important: AFTER the built-in imports, so that `register` & friends are already
+# available in the package namespace if a plugin uses
+# `from dbression.fixtures import register` instead of importing directly from
+# `dbression.fixtures.base`.
+from dbression.fixtures.plugins import load_plugins as _load_plugins  # noqa: E402
+
+_load_plugins()
+
+__all__ = [
+    "Fixture",
+    "FixtureContext",
+    "FixtureResult",
+    "REGISTRY",
+    "register",
+    "resolve_fixture",
+]

dbression/fixtures/base.py

@@ -0,0 +1,89 @@
+"""Fixture base class, context, and registry.
+
+DBFit names fixtures like ``Execute Procedure``, ``Execute Procedure Expect Exception``,
+etc. We map the fixture name (case-insensitive, normalized to lower + single spaces) to a
+Python class that implements ``run()``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, ClassVar
+
+from sqlalchemy.engine import Connection
+
+from dbression.parser.ast import Table
+from dbression.symbols import SymbolTable
+
+
+@dataclass(slots=True)
+class FixtureResult:
+    """Result of a single fixture invocation.
+
+    `passed` is True when the fixture met its expectation.
+    `message` is a short status line (single line).
+    `details` carries the verbose output on failure (exception, row diff, etc.).
+    """
+
+    passed: bool
+    message: str = ""
+    details: str = ""
+
+
+@dataclass(slots=True)
+class StoredQuery:
+    """Stored query result for `Store Query` / `Compare Stored Queries`."""
+
+    columns: list[str]
+    rows: list[tuple]
+
+
+@dataclass(slots=True)
+class FixtureContext:
+    """Runtime context the runner passes to each fixture."""
+
+    conn: Connection
+    symbols: SymbolTable
+    # Stash for `Store Query` — spans the whole suite so `Compare Stored Queries` can
+    # reference snapshots across multiple pages.
+    stored: dict[str, StoredQuery] = field(default_factory=dict)
+    # Reserved for future fixture side effects.
+    notes: list[str] = field(default_factory=list)
+
+
+class Fixture:
+    """Abstract fixture base class.
+
+    Concrete fixtures implement ``run(table, context)``. The constructor takes no
+    arguments — instances are stateless throwaway objects, one per table evaluation.
+    """
+
+    name: ClassVar[str] = ""
+
+    def run(self, table: Table, ctx: FixtureContext) -> FixtureResult:  # pragma: no cover
+        raise NotImplementedError
+
+
+REGISTRY: dict[str, type[Fixture]] = {}
+
+
+def _normalize(name: str) -> str:
+    return " ".join(name.strip().lower().split())
+
+
+def register(name: str) -> Callable[[type[Fixture]], type[Fixture]]:
+    """Decorator: register a fixture class under a display name.
+
+    Multiple registrations (aliases) are allowed — just apply the decorator multiple times.
+    """
+
+    def deco(cls: type[Fixture]) -> type[Fixture]:
+        REGISTRY[_normalize(name)] = cls
+        if not cls.name:
+            cls.name = name
+        return cls
+
+    return deco
+
+
+def resolve_fixture(name: str) -> type[Fixture] | None:
+    return REGISTRY.get(_normalize(name))