pytest-duckdb 0.1.0__tar.gz

pytest_duckdb-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: |
+          coverage run -m pytest
+          coverage report --fail-under=80
+          coverage xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+        continue-on-error: true
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pytest_duckdb-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+*.pyc
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.ruff_cache/

pytest_duckdb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Annas Mazhar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_duckdb-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: pytest-duckdb
+Version: 0.1.0
+Summary: pytest plugin for SQL pipeline testing with DuckDB — load fixtures, run queries, snapshot results
+Project-URL: Homepage, https://github.com/AnnasMazhar/pytest-duckdb
+Project-URL: Issues, https://github.com/AnnasMazhar/pytest-duckdb/issues
+Project-URL: Source, https://github.com/AnnasMazhar/pytest-duckdb
+Author-email: Annas Mazhar <annas.mazhar10@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-engineering,duckdb,pytest,snapshot,sql,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: duckdb>=0.9.0
+Requires-Dist: pytest>=7.0
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-duckdb
+
+[![CI](https://github.com/AnnasMazhar/pytest-duckdb/actions/workflows/ci.yml/badge.svg)](https://github.com/AnnasMazhar/pytest-duckdb/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pytest-duckdb.svg)](https://pypi.org/project/pytest-duckdb/)
+[![Python](https://img.shields.io/pypi/pyversions/pytest-duckdb.svg)](https://pypi.org/project/pytest-duckdb/)
+
+SQL pipeline testing made trivial. Load fixture CSVs as tables, run your queries, snapshot the results.
+
+## Install
+
+```bash
+pip install pytest-duckdb
+```
+
+## Quick Start
+
+Place CSV files in `tests/fixtures/`:
+
+```
+tests/
+  fixtures/
+    orders.csv
+    customers.csv
+  test_queries.py
+```
+
+They become tables automatically:
+
+```python
+def test_revenue_query(duckdb_session, sql_snapshot):
+    result = duckdb_session.execute(
+        "SELECT * FROM orders WHERE amount > 100"
+    ).fetchall()
+
+    # First run saves the snapshot, subsequent runs diff against it
+    sql_snapshot(result)
+```
+
+## Features
+
+- **Zero config** — fixture CSVs in `tests/fixtures/` auto-load as tables
+- **Snapshot testing** — first run saves output, subsequent runs diff
+- **Raw SQL files** — test `.sql` files directly without dbt
+- **Ephemeral** — each test gets a fresh in-memory DuckDB
+- **Fast** — DuckDB is embedded, no Docker, no network
+
+## Fixture Loading
+
+CSVs loaded by file stem become table names. `orders.csv` → `orders` table.
+
+```python
+def test_join(duckdb_session):
+    result = duckdb_session.execute("""
+        SELECT c.name, o.amount
+        FROM orders o JOIN customers c ON o.customer_id = c.id
+    """).fetchall()
+    assert len(result) > 0
+```
+
+## SQL File Testing
+
+```python
+@pytest.mark.sql("queries/revenue_by_month.sql")
+def test_revenue_by_month(sql_result, sql_snapshot):
+    sql_snapshot(sql_result)
+```
+
+## Snapshot Update
+
+Regenerate all snapshots when your expected output changes:
+
+```bash
+pytest --snapshot-update
+```
+
+## License
+
+MIT

pytest_duckdb-0.1.0/README.md

@@ -0,0 +1,78 @@
+# pytest-duckdb
+
+[![CI](https://github.com/AnnasMazhar/pytest-duckdb/actions/workflows/ci.yml/badge.svg)](https://github.com/AnnasMazhar/pytest-duckdb/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pytest-duckdb.svg)](https://pypi.org/project/pytest-duckdb/)
+[![Python](https://img.shields.io/pypi/pyversions/pytest-duckdb.svg)](https://pypi.org/project/pytest-duckdb/)
+
+SQL pipeline testing made trivial. Load fixture CSVs as tables, run your queries, snapshot the results.
+
+## Install
+
+```bash
+pip install pytest-duckdb
+```
+
+## Quick Start
+
+Place CSV files in `tests/fixtures/`:
+
+```
+tests/
+  fixtures/
+    orders.csv
+    customers.csv
+  test_queries.py
+```
+
+They become tables automatically:
+
+```python
+def test_revenue_query(duckdb_session, sql_snapshot):
+    result = duckdb_session.execute(
+        "SELECT * FROM orders WHERE amount > 100"
+    ).fetchall()
+
+    # First run saves the snapshot, subsequent runs diff against it
+    sql_snapshot(result)
+```
+
+## Features
+
+- **Zero config** — fixture CSVs in `tests/fixtures/` auto-load as tables
+- **Snapshot testing** — first run saves output, subsequent runs diff
+- **Raw SQL files** — test `.sql` files directly without dbt
+- **Ephemeral** — each test gets a fresh in-memory DuckDB
+- **Fast** — DuckDB is embedded, no Docker, no network
+
+## Fixture Loading
+
+CSVs loaded by file stem become table names. `orders.csv` → `orders` table.
+
+```python
+def test_join(duckdb_session):
+    result = duckdb_session.execute("""
+        SELECT c.name, o.amount
+        FROM orders o JOIN customers c ON o.customer_id = c.id
+    """).fetchall()
+    assert len(result) > 0
+```
+
+## SQL File Testing
+
+```python
+@pytest.mark.sql("queries/revenue_by_month.sql")
+def test_revenue_by_month(sql_result, sql_snapshot):
+    sql_snapshot(sql_result)
+```
+
+## Snapshot Update
+
+Regenerate all snapshots when your expected output changes:
+
+```bash
+pytest --snapshot-update
+```
+
+## License
+
+MIT

pytest_duckdb-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytest-duckdb"
+version = "0.1.0"
+description = "pytest plugin for SQL pipeline testing with DuckDB — load fixtures, run queries, snapshot results"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Annas Mazhar", email = "annas.mazhar10@gmail.com" }]
+keywords = ["pytest", "duckdb", "sql", "testing", "data-engineering", "snapshot"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "pytest>=7.0",
+    "duckdb>=0.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.4.0",
+    "pytest-cov>=5.0",
+    "coverage>=7.0",
+    "pandas>=2.0",
+]
+
+[project.entry-points.pytest11]
+duckdb = "pytest_duckdb.plugin"
+
+[project.urls]
+Homepage = "https://github.com/AnnasMazhar/pytest-duckdb"
+Issues = "https://github.com/AnnasMazhar/pytest-duckdb/issues"
+Source = "https://github.com/AnnasMazhar/pytest-duckdb"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytest_duckdb"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.coverage.run]
+source = ["pytest_duckdb"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "except ImportError:",
+]

pytest_duckdb-0.1.0/src/pytest_duckdb/__init__.py

@@ -0,0 +1,3 @@
+"""pytest-duckdb: SQL pipeline testing made trivial."""
+
+__version__ = "0.1.0"

pytest_duckdb-0.1.0/src/pytest_duckdb/fixtures.py

@@ -0,0 +1,50 @@
+"""CSV fixture loading — reads CSV files from a directory into DuckDB tables."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import duckdb
+
+
+def load_csvs(conn: duckdb.DuckDBPyConnection, fixtures_dir: str) -> None:
+    """Load all CSV files from *fixtures_dir* as DuckDB tables.
+
+    Each CSV file becomes a table named after its stem (filename without extension).
+    Uses ``read_csv_auto`` for schema inference.  Non-existent directories are
+    silently ignored so that tests without fixtures work out of the box.
+
+    Args:
+        conn: An open DuckDB connection.
+        fixtures_dir: Absolute or project-relative path to the CSV directory.
+    """
+    path = Path(fixtures_dir)
+    if not path.is_dir():
+        return
+
+    csv_files = sorted(path.glob("*.csv"))
+    for csv_file in csv_files:
+        table_name = csv_file.stem
+        conn.execute(
+            f'CREATE TABLE "{table_name}" AS '
+            f"SELECT * FROM read_csv_auto('{csv_file}')"
+        )
+
+
+def read_sql_file(path: str) -> str:
+    """Read and return the contents of a SQL file.
+
+    Args:
+        path: Absolute or relative path to the ``.sql`` file.
+
+    Returns:
+        The file contents as a string.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+    """
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f"SQL file not found: {path}")
+    with open(path) as fh:
+        return fh.read()

pytest_duckdb-0.1.0/src/pytest_duckdb/plugin.py

@@ -0,0 +1,254 @@
+"""pytest plugin registration — fixtures, markers, and CLI options.
+
+Provides three fixtures:
+
+* ``duckdb_session`` – function-scoped in-memory DuckDB with CSV fixtures
+  auto-loaded.
+* ``sql_result`` – executes a ``.sql`` file referenced via ``@pytest.mark.sql``.
+* ``sql_snapshot`` – callable fixture for Parquet snapshot testing.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+import pytest
+
+from .fixtures import load_csvs, read_sql_file
+from .snapshot import compare, save
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register CLI options and ini-file keys."""
+    parser.addini(
+        "duckdb_fixtures_dir",
+        type="string",
+        default="tests/fixtures",
+        help="Directory containing CSV fixture files",
+    )
+    parser.addini(
+        "duckdb_snapshots_dir",
+        type="string",
+        default="tests/__snapshots__",
+        help="Directory for Parquet snapshot files",
+    )
+    group = parser.getgroup("duckdb")
+    group.addoption(
+        "--snapshot-update",
+        action="store_true",
+        default=False,
+        help="Regenerate all Parquet snapshots instead of comparing",
+    )
+    group.addoption(
+        "--duckdb-fixtures-dir",
+        action="store",
+        default=None,
+        metavar="PATH",
+        help="Directory containing CSV fixture files (default: tests/fixtures)",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Register the ``sql`` marker and expand docstring."""
+    config.addinivalue_line(
+        "markers",
+        "sql(path): mark a test to run a SQL file; "
+        "the path is resolved relative to the project root.",
+    )
+
+    # Persist resolved config options.
+    config.duckdb_fixtures_dir = _resolve_option(
+        config,
+        cli_name="--duckdb-fixtures-dir",
+        ini_name="duckdb_fixtures_dir",
+        default="tests/fixtures",
+    )
+
+    config.duckdb_snapshots_dir = _resolve_ini_option(
+        config,
+        ini_name="duckdb_snapshots_dir",
+        default="tests/__snapshots__",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="function")
+def duckdb_session(request: pytest.FixtureRequest):
+    """Function-scoped DuckDB in-memory session with auto-loaded CSV fixtures.
+
+    CSVs in the configured fixtures directory are loaded as tables named
+    after the file stem.  If the directory does not exist the session is
+    returned empty with no error.
+
+    Yields:
+        ``duckdb.DuckDBPyConnection`` -- close on teardown.
+    """
+    import duckdb
+
+    conn = duckdb.connect(":memory:")
+    fixtures_dir = _resolve_path(
+        request.config.duckdb_fixtures_dir,
+        request.config.rootpath,
+    )
+    load_csvs(conn, fixtures_dir)
+    yield conn
+    conn.close()
+
+
+@pytest.fixture(scope="function")
+def sql_result(
+    duckdb_session,        # noqa: ANN001, ANN201
+    request: pytest.FixtureRequest,
+):
+    """Fixture that executes a SQL file referenced by ``@pytest.mark.sql``.
+
+    Usage::
+
+        @pytest.mark.sql("tests/queries/my_query.sql")
+        def test_something(sql_result):
+            assert len(sql_result) > 0
+
+    Returns a ``pandas.DataFrame`` if pandas is installed, otherwise a
+    :class:`~pytest_duckdb.snapshot.QueryResult` with ``.columns``.
+
+    Raises:
+        FileNotFoundError: The referenced SQL file does not exist.
+    """
+    marker = request.node.get_closest_marker("sql")
+    if marker is None:
+        return None
+
+    sql_path = _resolve_marker_path(marker, request)
+    query = read_sql_file(sql_path)
+    result = duckdb_session.execute(query)
+
+    from .snapshot import _cursor_to_result
+
+    return _cursor_to_result(result)
+
+
+@pytest.fixture(scope="function")
+def sql_snapshot(
+    duckdb_session,        # noqa: ANN001, ANN201
+    request: pytest.FixtureRequest,
+) -> Callable[..., None]:
+    """Callable fixture for Parquet snapshot testing.
+
+    Usage::
+
+        def test_query(sql_snapshot):
+            result = duckdb_session.execute("SELECT ...").fetchdf()
+            sql_snapshot(result)
+
+    **First run:** saves the result to ``{snapshots_dir}/{module}_{test}.parquet``
+    and passes.
+
+    **Subsequent runs:** loads the Parquet snapshot and asserts equality.  Raises
+    ``AssertionError`` with a clear diff on mismatch.
+
+    Pass ``--snapshot-update`` on the CLI to regenerate all snapshots.
+    """
+    snapshots_dir = _resolve_path(
+        request.config.duckdb_snapshots_dir,
+        request.config.rootpath,
+    )
+    update = request.config.getoption("--snapshot-update", default=False)
+
+    # Build a deterministic snapshot file name.
+    module_name = _module_name(request.node)
+    test_name = _test_name(request.node)
+    snapshot_path = os.path.join(
+        snapshots_dir, f"{module_name}_{test_name}.parquet",
+    )
+
+    def _snapshot(result: Any, name: Optional[str] = None) -> None:
+        """Save or compare *result* against the Parquet snapshot.
+
+        Args:
+            result: DataFrame or list-of-tuples to snapshot.
+            name: Optional override for the snapshot file name stem.
+
+        Raises:
+            AssertionError: On mismatch (when not updating).
+        """
+        nonlocal snapshot_path
+        if name is not None:
+            snapshot_path = os.path.join(
+                snapshots_dir, f"{module_name}_{name}.parquet",
+            )
+
+        if update or not os.path.isfile(snapshot_path):
+            save(duckdb_session, result, snapshot_path)
+        else:
+            compare(duckdb_session, result, snapshot_path)
+
+    return _snapshot
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_option(
+    config: pytest.Config,
+    cli_name: str,
+    ini_name: str,
+    default: str,
+) -> str:
+    """Resolve a config value from CLI → ini → default."""
+    cli_val = config.getoption(cli_name.replace("--", "").replace("-", "_"))
+    if cli_val is not None:
+        return cli_val
+    ini_val = config.getini(ini_name)
+    if ini_val:
+        return ini_val
+    return default
+
+
+def _resolve_ini_option(
+    config: pytest.Config,
+    ini_name: str,
+    default: str,
+) -> str:
+    """Resolve a config value from ini → default."""
+    ini_val = config.getini(ini_name)
+    if ini_val:
+        return ini_val
+    return default
+
+
+def _resolve_path(path_str: str, root: Path) -> str:
+    """Resolve a possibly-relative path against the project root."""
+    if not os.path.isabs(path_str):
+        return os.path.join(str(root), path_str)
+    return path_str
+
+
+def _resolve_marker_path(marker: pytest.Mark, request: pytest.FixtureRequest) -> str:
+    """Resolve the path from a ``@pytest.mark.sql`` marker."""
+    path = marker.args[0] if marker.args else marker.kwargs.get("path", "")
+    if not os.path.isabs(path):
+        return os.path.join(str(request.config.rootpath), path)
+    return path
+
+
+def _module_name(node: pytest.Item) -> str:
+    """Return a sanitised module name for snapshot file naming."""
+    # node.path gives the file path, e.g. tests/test_fixtures.py
+    fspath = getattr(node, "path", None) or getattr(node, "fspath", None)
+    if fspath:
+        stem = Path(str(fspath)).stem  # e.g. test_fixtures
+        return stem
+    return "unknown_module"
+
+
+def _test_name(node: pytest.Item) -> str:
+    """Return a sanitised test function name."""
+    return node.name.replace("[", "_").replace("]", "_").replace("/", "_")