behave-data 0.1.0__py3-none-any.whl

behave_data/__init__.py

@@ -0,0 +1,61 @@
+"""behave-data — Data management for Behave."""
+
+from behave_tables import (
+    ColumnMismatchError,
+    TableLike,
+    TableWrapper,
+    wrap,
+)
+
+from behave_data.config import Config
+from behave_data.diff import diff
+from behave_data.errors import (
+    BehaveDataError,
+    BuilderNotFoundError,
+    FixtureNotFoundError,
+    LoaderNotFoundError,
+    OptionalDependencyError,
+    RawTableError,
+    TableDiffError,
+    TypeConversionError,
+)
+from behave_data.hooks import before_step_hook, setup_data
+from behave_data.null import get_column_markers, is_null, resolve_null
+from behave_data.patch import apply_patches, revert_patches
+from behave_data.raw_table import RawTable, raw_table
+from behave_data.typed_table import TypedTableWrapper, typed_wrap
+from behave_data.types import TYPE_CONVERTERS, convert_cell, parse_column_header, register_type
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BehaveDataError",
+    "BuilderNotFoundError",
+    "ColumnMismatchError",
+    "Config",
+    "FixtureNotFoundError",
+    "LoaderNotFoundError",
+    "OptionalDependencyError",
+    "RawTable",
+    "RawTableError",
+    "TableDiffError",
+    "TableLike",
+    "TableWrapper",
+    "TYPE_CONVERTERS",
+    "TypeConversionError",
+    "TypedTableWrapper",
+    "apply_patches",
+    "before_step_hook",
+    "convert_cell",
+    "diff",
+    "get_column_markers",
+    "is_null",
+    "parse_column_header",
+    "raw_table",
+    "register_type",
+    "resolve_null",
+    "revert_patches",
+    "setup_data",
+    "typed_wrap",
+    "wrap",
+]

behave_data/config.py

@@ -0,0 +1,137 @@
+"""Configuration for behave-data."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from behave_data.errors import OptionalDependencyError
+
+DEFAULT_NULL_MARKERS: frozenset[str] = frozenset({"", "null", "None", "N/A"})
+
+_KNOWN_KEYS = frozenset(
+    {
+        "null_markers",
+        "null_markers_by_column",
+        "secret_backend",
+        "secret_path",
+        "load_base_dir",
+        "db_connections",
+        "type_overrides",
+    }
+)
+
+
+def _stringify_marker(m: object) -> str:
+    """Convert a marker value to string, handling YAML's null -> None."""
+    if m is None:
+        return "null"
+    return str(m)
+
+
+@dataclass(frozen=True)
+class Config:
+    """Configuration for behave-data.
+
+    Attributes:
+        null_markers: Global set of strings treated as null.
+        null_markers_by_column: Per-column null markers that override globals.
+        secret_backend: Backend for secret resolution (file, env, vault, aws).
+        secret_path: Directory path for file-based secrets.
+        load_base_dir: Base directory for relative file loading.
+        db_connections: Named database connection strings.
+        type_overrides: Per-column type overrides.
+    """
+
+    null_markers: frozenset[str] = DEFAULT_NULL_MARKERS
+    null_markers_by_column: dict[str, frozenset[str]] = field(default_factory=dict)
+    secret_backend: str = "file"
+    secret_path: str = "secrets/"
+    load_base_dir: str = "features/data/"
+    db_connections: dict[str, str] = field(default_factory=dict)
+    type_overrides: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Config:
+        """Create a Config from a dict, filtering unknown keys and converting lists to frozensets.
+
+        Args:
+            data: A dict with optional configuration keys.
+
+        Returns:
+            A Config instance with values from data, defaults for missing keys.
+        """
+        filtered = {k: v for k, v in data.items() if k in _KNOWN_KEYS}
+
+        if "null_markers" in filtered:
+            val = filtered["null_markers"]
+            if isinstance(val, list):
+                filtered["null_markers"] = frozenset(_stringify_marker(m) for m in val)
+            elif isinstance(val, frozenset):
+                filtered["null_markers"] = val
+            else:
+                filtered["null_markers"] = frozenset(_stringify_marker(m) for m in val)
+
+        if "null_markers_by_column" in filtered:
+            raw = filtered["null_markers_by_column"]
+            converted: dict[str, frozenset[str]] = {}
+            for col, markers in raw.items():
+                if isinstance(markers, list):
+                    converted[col] = frozenset(_stringify_marker(m) for m in markers)
+                elif isinstance(markers, frozenset):
+                    converted[col] = markers
+                else:
+                    converted[col] = frozenset(_stringify_marker(m) for m in markers)
+            filtered["null_markers_by_column"] = converted
+
+        return cls(**filtered)
+
+    @classmethod
+    def from_file(cls, path: str = "behave_data.yml") -> Config:
+        """Load Config from a YAML or JSON file.
+
+        If the file does not exist, returns default Config.
+        For ``.yml``/``.yaml`` files, uses PyYAML (lazy-import).
+        For ``.json`` files, uses ``json``.
+        Unknown extensions return default Config.
+
+        Args:
+            path: Path to the configuration file.
+
+        Returns:
+            A Config instance.
+
+        Raises:
+            OptionalDependencyError: If PyYAML is required but not installed.
+        """
+        p = Path(path)
+        if not p.exists():
+            return cls()
+
+        suffix = p.suffix.lower()
+
+        if suffix in (".yml", ".yaml"):
+            try:
+                import yaml
+            except ImportError:
+                raise OptionalDependencyError(
+                    "pyyaml",
+                    "YAML config loading",
+                    "pip install behave-data[yaml]",
+                ) from None
+            with p.open(encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+            if not isinstance(data, dict):
+                return cls()
+            return cls.from_dict(data)
+
+        if suffix == ".json":
+            with p.open(encoding="utf-8") as f:
+                data = json.load(f)
+            if not isinstance(data, dict):
+                return cls()
+            return cls.from_dict(data)
+
+        return cls()

behave_data/diff.py

@@ -0,0 +1,182 @@
+"""Table diff with Cucumber-style output."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from behave_tables.wrapper import TableLike, TableWrapper
+
+from behave_data.errors import TableDiffError
+
+
+def diff(
+    expected: TableLike,
+    actual: Any,
+    *,
+    ordered: bool = True,
+    ignore_columns: list[str] | None = None,
+    surplus_columns: bool = True,
+) -> None:
+    """Compare two tables and raise TableDiffError if they differ.
+
+    Args:
+        expected: The expected table (table-like with ``headings`` and ``rows``).
+        actual: The actual data. Accepts a table-like object, ``list[dict]``,
+            or a single ``dict`` (wrapped in a list). ``list[list]`` raises
+            ``ValueError`` because headers are needed.
+        ordered: If True, rows must be in the same order.
+        ignore_columns: Column names to exclude from comparison.
+        surplus_columns: If False, extra columns in actual are removed before
+            comparison (they don't cause a diff).
+
+    Raises:
+        ValueError: If ``actual`` is a ``list[list]`` (needs headers).
+        TableDiffError: If the tables differ, with a Cucumber-style diff output.
+    """
+    ignore_set = set(ignore_columns) if ignore_columns else set()
+
+    exp_wrapper = TableWrapper(expected)
+    exp_headers = [h for h in exp_wrapper.headers if h not in ignore_set]
+    exp_rows = exp_wrapper.as_dicts()
+
+    act_headers, act_rows = _normalize_actual(actual, exp_headers)
+
+    # Filter ignore_columns from actual
+    act_headers = [h for h in act_headers if h not in ignore_set]
+    act_rows = [{k: v for k, v in row.items() if k not in ignore_set} for row in act_rows]
+
+    # Filter ignore_columns from expected
+    exp_rows = [{k: v for k, v in row.items() if k not in ignore_set} for row in exp_rows]
+
+    # Handle surplus columns
+    if not surplus_columns:
+        exp_set = set(exp_headers)
+        act_rows = [{k: v for k, v in row.items() if k in exp_set} for row in act_rows]
+        act_headers = [h for h in act_headers if h in exp_set]
+
+    # Build diff output
+    diff_lines: list[str] = []
+
+    # Header diff
+    if exp_headers != act_headers:
+        diff_lines.append("Tables were not identical:")
+        diff_lines.append(f"  Headers differ: expected {exp_headers}, got {act_headers}")
+        # Use expected headers for row comparison
+        compare_headers = exp_headers
+    else:
+        compare_headers = exp_headers
+
+    # Row diff
+    if ordered:
+        row_diffs = _diff_ordered(exp_rows, act_rows, compare_headers)
+    else:
+        row_diffs = _diff_unordered(exp_rows, act_rows, compare_headers)
+
+    if row_diffs:
+        if not diff_lines:
+            diff_lines.append("Tables were not identical:")
+        diff_lines.extend(row_diffs)
+
+    if diff_lines:
+        output = "\n".join(diff_lines)
+        raise TableDiffError(output)
+
+
+def _normalize_actual(
+    actual: Any,
+    exp_headers: list[str],
+) -> tuple[list[str], list[dict[str, str]]]:
+    """Normalize actual into (headers, rows).
+
+    Args:
+        actual: The actual data to normalize.
+        exp_headers: Expected headers, used as fallback for dict normalization.
+
+    Returns:
+        A tuple of (headers, list of row dicts).
+
+    Raises:
+        ValueError: If actual is a list[list] (needs headers).
+    """
+    if isinstance(actual, dict):
+        actual = [actual]
+
+    if isinstance(actual, list) and len(actual) > 0 and isinstance(actual[0], dict):
+        # list[dict] — infer headers from first dict keys
+        headers = list(actual[0].keys())
+        rows = [dict(d) for d in actual]
+        return headers, rows
+
+    if isinstance(actual, list) and len(actual) > 0 and isinstance(actual[0], (list, tuple)):
+        raise ValueError(
+            "Cannot diff list[list] — headers are required. "
+            "Provide a table-like object or list[dict] instead."
+        )
+
+    if isinstance(actual, list) and len(actual) == 0:
+        return list(exp_headers), []
+
+    # Table-like object with headings + rows
+    wrapper = TableWrapper(actual)
+    return list(wrapper.headers), wrapper.as_dicts()
+
+
+def _diff_ordered(
+    expected: list[dict[str, str]],
+    actual: list[dict[str, str]],
+    headers: list[str],
+) -> list[str]:
+    """Compare tables in order and return diff lines if different."""
+    diff_lines: list[str] = []
+    max_rows = max(len(expected), len(actual))
+
+    for i in range(max_rows):
+        if i < len(expected) and i < len(actual):
+            exp_vals = [str(expected[i].get(h, "")) for h in headers]
+            act_vals = [str(actual[i].get(h, "")) for h in headers]
+            if exp_vals != act_vals:
+                diff_lines.append(f"      - {_format_row(exp_vals)}")
+                diff_lines.append(f"      + {_format_row(act_vals)}")
+        elif i < len(expected):
+            exp_vals = [str(expected[i].get(h, "")) for h in headers]
+            diff_lines.append(f"    - {_format_row(exp_vals)}")
+        else:
+            act_vals = [str(actual[i].get(h, "")) for h in headers]
+            diff_lines.append(f"    + {_format_row(act_vals)}")
+
+    return diff_lines
+
+
+def _diff_unordered(
+    expected: list[dict[str, str]],
+    actual: list[dict[str, str]],
+    headers: list[str],
+) -> list[str]:
+    """Compare tables ignoring row order and return diff lines if different."""
+    exp_tuples = [tuple(str(row.get(h, "")) for h in headers) for row in expected]
+    act_tuples = [tuple(str(row.get(h, "")) for h in headers) for row in actual]
+
+    exp_remaining = list(exp_tuples)
+    act_remaining = list(act_tuples)
+
+    missing_rows: list[tuple[str, ...]] = []
+    for row in exp_remaining:
+        if row in act_remaining:
+            act_remaining.remove(row)
+        else:
+            missing_rows.append(row)
+
+    surplus_rows = list(act_remaining)
+
+    diff_lines: list[str] = []
+    for row in missing_rows:
+        diff_lines.append(f"    - {_format_row(list(row))}")
+    for row in surplus_rows:
+        diff_lines.append(f"    + {_format_row(list(row))}")
+
+    return diff_lines
+
+
+def _format_row(values: list[str]) -> str:
+    """Format a single row as a Cucumber-style table row."""
+    return f"| {' | '.join(values)} |"

behave_data/errors.py

@@ -0,0 +1,100 @@
+"""Custom exceptions for behave-data."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("behave_data")
+logger.addHandler(logging.NullHandler())
+
+
+class BehaveDataError(Exception):
+    """Base class for all behave-data errors."""
+
+
+class TypeConversionError(BehaveDataError):
+    """Raised when a cell value cannot be converted to the target type.
+
+    Attributes:
+        column: The column name where the conversion failed.
+        value: The original value that could not be converted.
+        target_type: The name of the target type.
+        cause: The underlying exception that caused the failure.
+    """
+
+    def __init__(self, column: str, value: object, target_type: str, cause: Exception) -> None:
+        self.column = column
+        self.value = value
+        self.target_type = target_type
+        self.cause = cause
+        super().__init__(
+            f"Cannot convert column '{column}' value {value!r} to {target_type}: {cause}"
+        )
+
+
+class TableDiffError(AssertionError):
+    """Raised when two tables are not identical.
+
+    Attributes:
+        diff_output: The human-readable diff string.
+    """
+
+    def __init__(self, diff_output: str) -> None:
+        self.diff_output = diff_output
+        super().__init__(diff_output)
+
+
+class FixtureNotFoundError(BehaveDataError):
+    """Raised when a requested fixture is not registered.
+
+    Attributes:
+        name: The fixture name that was not found.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"Fixture '{name}' not registered.")
+
+
+class BuilderNotFoundError(BehaveDataError):
+    """Raised when a requested builder is not registered.
+
+    Attributes:
+        name: The builder name that was not found.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"Builder '{name}' not registered.")
+
+
+class LoaderNotFoundError(BehaveDataError):
+    """Raised when no loader is found for a given source.
+
+    Attributes:
+        source: The source string that could not be matched to a loader.
+    """
+
+    def __init__(self, source: str) -> None:
+        self.source = source
+        super().__init__(f"No loader found for source: {source!r}")
+
+
+class OptionalDependencyError(BehaveDataError):
+    """Raised when an optional dependency is required but not installed.
+
+    Attributes:
+        package: The name of the missing package.
+        feature: The feature that requires the package.
+        install_cmd: The command to install the package.
+    """
+
+    def __init__(self, package: str, feature: str, install_cmd: str) -> None:
+        self.package = package
+        self.feature = feature
+        self.install_cmd = install_cmd
+        super().__init__(f"{package} is required for {feature}. Install it with: {install_cmd}")
+
+
+class RawTableError(BehaveDataError):
+    """Raised when raw table operations fail."""

behave_data/examples.py

@@ -0,0 +1,107 @@
+"""Dynamic Examples loading for Behave features."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from behave_data.config import Config
+from behave_data.loaders import load as _load
+
+_LOAD_TAG_PATTERN = re.compile(r"@load_examples:(.+)")
+
+
+def _find_load_tag(scenario: Any) -> str | None:
+    """Find a @load_examples:source tag on a scenario or its feature.
+
+    Args:
+        scenario: A Behave scenario object with ``tags`` and ``feature.tags``.
+
+    Returns:
+        The source string (trimmed) if found, else None.
+    """
+    tags = list(getattr(scenario, "tags", []))
+    feature = getattr(scenario, "feature", None)
+    if feature is not None:
+        tags.extend(getattr(feature, "tags", []))
+
+    for tag in tags:
+        match = _LOAD_TAG_PATTERN.match(tag.strip())
+        if match:
+            return match.group(1).strip()
+    return None
+
+
+def _replace_example_rows(example: Any, data: list[dict[str, Any]]) -> None:
+    """Replace the rows in an Examples block with loaded data.
+
+    Creates new Row objects preserving line numbers.
+
+    Args:
+        example: A Behave Examples object with ``table``.
+        data: List of dicts from the loader.
+    """
+    if not data:
+        example.table.rows = []
+        return
+
+    headers = list(data[0].keys())
+
+    try:
+        from behave.model import Row
+    except ImportError:
+        example.table.headings = headers
+        example.table.rows = []
+        for row_data in data:
+            cells = [str(row_data.get(h, "")) for h in headers]
+            example.table.rows.append(_SimpleRow(cells))
+        return
+
+    example.table.headings = headers
+    example.table.rows = []
+    for row_data in data:
+        cells = [str(row_data.get(h, "")) for h in headers]
+        line = getattr(example, "line", 0)
+        example.table.rows.append(Row(headers, cells, line))
+
+
+class _SimpleRow:
+    """Fallback Row when behave.model.Row is not available."""
+
+    def __init__(self, cells: list[str]) -> None:
+        self.cells = cells
+
+    def __getitem__(self, index: int) -> str:
+        return self.cells[index]
+
+    def as_dict(self) -> dict[str, str]:
+        return dict(zip(self._headers, self.cells, strict=False))
+
+
+def load_examples_for_feature(feature: Any, config: Config) -> None:
+    """Load dynamic Examples for all scenarios in a feature.
+
+    Iterates ``feature.scenarios``, finds ``@load_examples:source`` tags,
+    and replaces Example rows with data loaded from the source.
+
+    Args:
+        feature: A Behave Feature object with ``scenarios``.
+        config: Configuration for loader resolution.
+    """
+    scenarios = getattr(feature, "scenarios", [])
+    if not scenarios:
+        return
+
+    for scenario in scenarios:
+        source = _find_load_tag(scenario)
+        if source is None:
+            continue
+
+        data = _load(source, config)
+
+        examples = getattr(scenario, "examples", [])
+        if not examples:
+            continue
+
+        for example in examples:
+            _replace_example_rows(example, data)

behave_data/hooks.py

@@ -0,0 +1,80 @@
+"""Behave hooks for behave-data MVP."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from behave_data.config import Config
+from behave_data.manager import DataManager
+from behave_data.patch import apply_patches
+
+_PLACEHOLDER_PATTERN = re.compile(r"\{([^}]+)\}")
+
+
+def setup_data(context: Any, config: Config | None = None) -> None:
+    """Initialize behave-data for a Behave run.
+
+    Stores the configuration, creates a DataManager, and applies table patches.
+
+    Args:
+        context: The Behave context object.
+        config: Configuration to use. If None, loads from ``behave_data.yml``.
+    """
+    cfg = config if config is not None else Config.from_file("behave_data.yml")
+    context.data = DataManager(cfg)
+    apply_patches()
+
+
+def _resolve_placeholders(value: str, context: Any) -> str:
+    """Resolve ``{placeholder}`` patterns in a string using context attributes.
+
+    Supports nested attribute access via dot notation, e.g. ``{user.name}``.
+
+    Args:
+        value: The string potentially containing placeholders.
+        context: The Behave context object with attributes.
+
+    Returns:
+        The string with placeholders replaced by resolved values.
+    """
+
+    def replacer(match: re.Match[str]) -> str:
+        key = match.group(1)
+        obj: Any = context
+        for part in key.split("."):
+            if hasattr(obj, part):
+                obj = getattr(obj, part)
+            else:
+                return match.group(0)
+        return str(obj)
+
+    return _PLACEHOLDER_PATTERN.sub(replacer, value)
+
+
+def before_step_hook(context: Any, step: Any) -> None:
+    """Resolve placeholders in table cells before each step.
+
+    This hook does NOT mutate the original table. If the step has an
+    associated table, a copy of the table is created with resolved
+    placeholders and assigned to ``context.table``.
+
+    Args:
+        context: The Behave context object.
+        step: The step about to be executed.
+    """
+    table = getattr(step, "table", None)
+    if table is None:
+        return
+
+    from behave_data.raw_table import RawTable
+
+    raw = RawTable(table)
+    resolved_rows: list[list[str]] = []
+    for row in raw.rows:
+        resolved_rows.append([_resolve_placeholders(cell, context) for cell in row])
+
+    context.resolved_table = {
+        "headings": list(raw[0]),
+        "rows": resolved_rows,
+    }