behave-data 0.1.0__py3-none-any.whl

behave_data/loaders/__init__.py

@@ -0,0 +1,109 @@
+"""Loader registry and Protocol for behave-data."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+from behave_data.config import Config
+from behave_data.errors import LoaderNotFoundError
+
+_EXTENSION_MAP: dict[str, str] = {
+    ".csv": "csv",
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".xlsx": "xlsx",
+}
+
+
+@runtime_checkable
+class Loader(Protocol):
+    """Protocol for data loaders."""
+
+    def load(self, source: str, config: Config) -> list[dict[str, Any]]:
+        """Load data from a source and return a list of dicts."""
+        ...
+
+
+_LOADERS: dict[str, str] = {
+    "csv": "behave_data.loaders.csv:CsvLoader",
+    "json": "behave_data.loaders.json:JsonLoader",
+    "yaml": "behave_data.loaders.yaml:YamlLoader",
+    "xlsx": "behave_data.loaders.excel:ExcelLoader",
+    "sql": "behave_data.loaders.sql:SqlLoader",
+    "http": "behave_data.loaders.http:HttpLoader",
+}
+
+
+def _resolve_loader(schema: str) -> Loader:
+    """Lazy-import and return a loader instance for the given schema."""
+    if schema not in _LOADERS:
+        raise LoaderNotFoundError(schema)
+    module_path, class_name = _LOADERS[schema].split(":")
+    import importlib
+
+    module = importlib.import_module(module_path)
+    loader_cls = getattr(module, class_name)
+    return loader_cls()
+
+
+def _detect_schema(source: str) -> str | None:
+    """Detect the schema prefix from a source string.
+
+    If source contains a schema prefix (e.g. ``csv:``), return it.
+    Otherwise, detect from file extension.
+    """
+    if ":" in source:
+        prefix = source.split(":", 1)[0].lower()
+        if prefix in _LOADERS:
+            return prefix
+    p = Path(source)
+    ext = p.suffix.lower()
+    if ext in _EXTENSION_MAP:
+        return _EXTENSION_MAP[ext]
+    return None
+
+
+def _resolve_path(source: str, config: Config) -> str:
+    """Resolve a source path, using config.load_base_dir for relative paths."""
+    p = Path(source)
+    if p.is_absolute() or ":" in source:
+        return source
+    return str(Path(config.load_base_dir) / source)
+
+
+def load(source: str, config: Config | None = None) -> list[dict[str, Any]]:
+    """Load data from a source string.
+
+    Detects the schema prefix (e.g. ``csv:``) or file extension,
+    resolves relative paths against ``config.load_base_dir``,
+    and delegates to the appropriate loader.
+
+    Args:
+        source: Source string with optional schema prefix.
+        config: Configuration with load_base_dir and connection settings.
+
+    Returns:
+        List of dicts representing loaded data.
+
+    Raises:
+        LoaderNotFoundError: If no loader matches the source.
+    """
+    cfg = config if config is not None else Config()
+
+    schema = _detect_schema(source)
+    if schema is None:
+        raise LoaderNotFoundError(source)
+
+    loader = _resolve_loader(schema)
+
+    if ":" in source and source.split(":", 1)[0].lower() == schema:
+        path = source.split(":", 1)[1]
+    else:
+        path = source
+
+    if schema not in ("sql", "http"):
+        path = _resolve_path(path, cfg)
+
+    return loader.load(path, cfg)

behave_data/loaders/csv.py

@@ -0,0 +1,26 @@
+"""CSV loader for behave-data."""
+
+from __future__ import annotations
+
+import csv
+from typing import Any
+
+from behave_data.config import Config
+
+
+class CsvLoader:
+    """Load data from CSV files using csv.DictReader."""
+
+    def load(self, source: str, config: Config) -> list[dict[str, Any]]:
+        """Load CSV data from a file path.
+
+        Args:
+            source: Path to the CSV file.
+            config: Configuration (unused for CSV, but required by Protocol).
+
+        Returns:
+            List of dicts, one per row. Empty list if file is empty.
+        """
+        with open(source, encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+            return list(reader)

behave_data/loaders/excel.py

@@ -0,0 +1,54 @@
+"""Excel loader for behave-data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from behave_data.config import Config
+from behave_data.errors import OptionalDependencyError
+
+
+class ExcelLoader:
+    """Load data from Excel (.xlsx) files using openpyxl."""
+
+    def load(self, source: str, config: Config) -> list[dict[str, Any]]:
+        """Load Excel data from a file path.
+
+        First row is treated as headers.
+
+        Args:
+            source: Path to the Excel file.
+            config: Configuration (unused for Excel, but required by Protocol).
+
+        Returns:
+            List of dicts, one per data row.
+
+        Raises:
+            OptionalDependencyError: If openpyxl is not installed.
+        """
+        try:
+            import openpyxl
+        except ImportError:
+            raise OptionalDependencyError(
+                "openpyxl",
+                "Excel loading",
+                "pip install behave-data[excel]",
+            ) from None
+
+        wb = openpyxl.load_workbook(source, read_only=True)
+        ws = wb.active
+        rows = list(ws.iter_rows(values_only=True))
+        wb.close()
+
+        if not rows:
+            return []
+
+        headers = [str(h) if h is not None else "" for h in rows[0]]
+        result: list[dict[str, Any]] = []
+        for row in rows[1:]:
+            row_dict: dict[str, Any] = {}
+            for i, cell in enumerate(row):
+                key = headers[i] if i < len(headers) else f"col_{i}"
+                row_dict[key] = cell
+            result.append(row_dict)
+        return result

behave_data/loaders/http.py

@@ -0,0 +1,61 @@
+"""HTTP loader for behave-data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from behave_data.config import Config
+from behave_data.errors import OptionalDependencyError
+
+
+class HttpLoader:
+    """Load data from HTTP endpoints using requests."""
+
+    def load(self, source: str, config: Config) -> list[dict[str, Any]]:
+        """Fetch data from an HTTP endpoint.
+
+        Source format: ``GET https://api.example.com/users`` or
+        ``POST https://api.example.com/users``.
+
+        Args:
+            source: HTTP method + URL string.
+            config: Configuration (unused for HTTP, but required by Protocol).
+
+        Returns:
+            List of dicts from the JSON response.
+
+        Raises:
+            OptionalDependencyError: If requests is not installed.
+        """
+        try:
+            import requests
+        except ImportError:
+            raise OptionalDependencyError(
+                "requests",
+                "HTTP loading",
+                "pip install behave-data[http]",
+            ) from None
+
+        parts = source.strip().split(None, 1)
+        if len(parts) == 2:
+            method, url = parts
+        else:
+            method = "GET"
+            url = parts[0]
+
+        method = method.upper()
+        if method == "GET":
+            response = requests.get(url, timeout=30)
+        elif method == "POST":
+            response = requests.post(url, timeout=30)
+        else:
+            raise ValueError(f"Unsupported HTTP method: {method}")
+
+        response.raise_for_status()
+        data = response.json()
+
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            return [data]
+        raise ValueError(f"HTTP response must be a list or dict, got {type(data).__name__}")

behave_data/loaders/json.py

@@ -0,0 +1,34 @@
+"""JSON loader for behave-data."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from behave_data.config import Config
+
+
+class JsonLoader:
+    """Load data from JSON files."""
+
+    def load(self, source: str, config: Config) -> list[dict[str, Any]]:
+        """Load JSON data from a file path.
+
+        Args:
+            source: Path to the JSON file.
+            config: Configuration (unused for JSON, but required by Protocol).
+
+        Returns:
+            List of dicts. If the JSON is a dict, wraps it in a list.
+
+        Raises:
+            ValueError: If the JSON data is not a list or dict.
+        """
+        with open(source, encoding="utf-8") as f:
+            data = json.load(f)
+
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            return [data]
+        raise ValueError(f"JSON data must be a list or dict, got {type(data).__name__}")

behave_data/loaders/sql.py

@@ -0,0 +1,46 @@
+"""SQL loader for behave-data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from behave_data.config import Config
+from behave_data.errors import OptionalDependencyError
+
+
+class SqlLoader:
+    """Load data from SQL queries using SQLAlchemy."""
+
+    def load(self, source: str, config: Config) -> list[dict[str, Any]]:
+        """Execute a SQL query and return results as list of dicts.
+
+        Args:
+            source: SQL query string.
+            config: Configuration with db_connections mapping.
+
+        Returns:
+            List of dicts, one per row.
+
+        Raises:
+            OptionalDependencyError: If SQLAlchemy is not installed.
+            KeyError: If the database name is not in config.db_connections.
+        """
+        try:
+            import sqlalchemy
+        except ImportError:
+            raise OptionalDependencyError(
+                "sqlalchemy",
+                "SQL loading",
+                "pip install behave-data[sql]",
+            ) from None
+
+        db_name = getattr(config, "_sql_db_name", None) or "default"
+        connection_string = config.db_connections.get(db_name)
+        if connection_string is None:
+            raise KeyError(f"Database '{db_name}' not found in config.db_connections")
+
+        engine = sqlalchemy.create_engine(connection_string)
+        with engine.connect() as conn:
+            result = conn.execute(sqlalchemy.text(source))
+            columns = list(result.keys())
+            return [dict(zip(columns, row, strict=False)) for row in result]

behave_data/loaders/yaml.py

@@ -0,0 +1,45 @@
+"""YAML loader for behave-data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from behave_data.config import Config
+from behave_data.errors import OptionalDependencyError
+
+
+class YamlLoader:
+    """Load data from YAML files."""
+
+    def load(self, source: str, config: Config) -> list[dict[str, Any]]:
+        """Load YAML data from a file path.
+
+        Args:
+            source: Path to the YAML file.
+            config: Configuration (unused for YAML, but required by Protocol).
+
+        Returns:
+            List of dicts. If the YAML is a dict, wraps it in a list.
+
+        Raises:
+            OptionalDependencyError: If PyYAML is not installed.
+        """
+        try:
+            import yaml
+        except ImportError:
+            raise OptionalDependencyError(
+                "pyyaml",
+                "YAML loading",
+                "pip install behave-data[yaml]",
+            ) from None
+
+        with open(source, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            return [data]
+        if data is None:
+            return []
+        raise ValueError(f"YAML data must be a list or dict, got {type(data).__name__}")

behave_data/manager.py

@@ -0,0 +1,20 @@
+"""Minimal DataManager stub for MVP.
+
+The full implementation comes in Fase 3.3.
+For now, it just stores the config.
+"""
+
+from __future__ import annotations
+
+from behave_data.config import Config
+
+
+class DataManager:
+    """Minimal data manager that stores configuration.
+
+    Attributes:
+        config: The behave-data configuration.
+    """
+
+    def __init__(self, config: Config) -> None:
+        self.config = config

behave_data/null.py

@@ -0,0 +1,65 @@
+"""Null handling for behave-data table cells."""
+
+from __future__ import annotations
+
+from behave_data.config import DEFAULT_NULL_MARKERS, Config
+
+
+def get_column_markers(column_name: str, config: Config) -> frozenset[str] | None:
+    """Get the per-column null markers for a specific column.
+
+    Args:
+        column_name: The column name.
+        config: The Config to query.
+
+    Returns:
+        A frozenset of null markers for the column, or None if no
+        per-column markers are defined.
+    """
+    return config.null_markers_by_column.get(column_name)
+
+
+def is_null(
+    value: str,
+    markers: frozenset[str] | None = None,
+    column_markers: frozenset[str] | None = None,
+) -> bool:
+    """Check if a value is a null marker.
+
+    Priority: ``column_markers`` > ``markers`` > ``DEFAULT_NULL_MARKERS``.
+
+    Args:
+        value: The string value to check.
+        markers: Global null markers. If None, defaults are used.
+        column_markers: Per-column markers that override global markers.
+
+    Returns:
+        True if the value is a null marker, False otherwise.
+    """
+    if column_markers is not None:
+        return value in column_markers
+    if markers is not None:
+        return value in markers
+    return value in DEFAULT_NULL_MARKERS
+
+
+def resolve_null(
+    value: str,
+    markers: frozenset[str] | None = None,
+    column_markers: frozenset[str] | None = None,
+) -> str | None:
+    """Resolve a null marker to None, or return the value unchanged.
+
+    Priority: ``column_markers`` > ``markers`` > ``DEFAULT_NULL_MARKERS``.
+
+    Args:
+        value: The string value to resolve.
+        markers: Global null markers. If None, defaults are used.
+        column_markers: Per-column markers that override global markers.
+
+    Returns:
+        None if the value is a null marker, otherwise the original value.
+    """
+    if is_null(value, markers, column_markers):
+        return None
+    return value

behave_data/patch.py

@@ -0,0 +1,153 @@
+"""Patch behave.model.Table with behave-data convenience methods."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from behave_data.config import Config
+from behave_data.diff import diff as _diff
+from behave_data.raw_table import RawTable
+from behave_data.typed_table import TypedTableWrapper
+from behave_data.typed_table import typed_wrap as _typed_wrap
+
+_ORIGINAL_METHODS: dict[str, Any] = {}
+_IS_PATCHED = False
+
+_METHOD_NAMES = [
+    "typed_wrap",
+    "typed_dicts",
+    "typed_objects",
+    "clean_headers",
+    "to_dict",
+    "to_lists",
+    "to_pandas",
+    "raw_table",
+    "diff",
+]
+
+
+def _typed_wrap_method(self: Any, config: Config | None = None) -> TypedTableWrapper:
+    return _typed_wrap(self, config)
+
+
+def _typed_dicts(self: Any, config: Config | None = None) -> list[dict[str, Any]]:
+    return TypedTableWrapper(self, config).typed_dicts()
+
+
+def _typed_objects(self: Any, cls: type, config: Config | None = None) -> list[Any]:
+    return TypedTableWrapper(self, config).typed_objects(cls, config)
+
+
+def _clean_headers(self: Any) -> list[str]:
+    return TypedTableWrapper(self).clean_headers()
+
+
+def _to_dict(self: Any, config: Config | None = None) -> dict[Any, Any]:
+    return TypedTableWrapper(self, config).to_dict()
+
+
+def _to_lists(self: Any, config: Config | None = None) -> list[list[Any]]:
+    return TypedTableWrapper(self, config).to_lists()
+
+
+def _to_pandas(self: Any, config: Config | None = None) -> Any:
+    return TypedTableWrapper(self, config).to_pandas()
+
+
+def _raw_table(self: Any) -> RawTable:
+    return RawTable(self)
+
+
+def _diff_method(
+    self: Any,
+    other: Any,
+    *,
+    ordered: bool = True,
+    ignore_columns: list[str] | None = None,
+    surplus_columns: bool = True,
+) -> None:
+    _diff(
+        self,
+        other,
+        ordered=ordered,
+        ignore_columns=ignore_columns,
+        surplus_columns=surplus_columns,
+    )
+
+
+_IMPLEMENTATIONS = {
+    "typed_wrap": _typed_wrap_method,
+    "typed_dicts": _typed_dicts,
+    "typed_objects": _typed_objects,
+    "clean_headers": _clean_headers,
+    "to_dict": _to_dict,
+    "to_lists": _to_lists,
+    "to_pandas": _to_pandas,
+    "raw_table": _raw_table,
+    "diff": _diff_method,
+}
+
+
+def apply_patches() -> None:
+    """Add behave-data convenience methods to behave.model.Table.
+
+    This function is idempotent: calling it multiple times has no effect.
+    Each method is added as a bound method to the Table class.
+
+    Adds the following methods:
+        - typed_wrap(config=None)
+        - typed_dicts(config=None)
+        - typed_objects(cls, config=None)
+        - clean_headers()
+        - to_dict(config=None)
+        - to_lists(config=None)
+        - to_pandas(config=None)
+        - raw_table()
+        - diff(other, *, ordered=True, ignore_columns=None, surplus_columns=True)
+
+    Sets ``Table._behave_data_patched = True``.
+    """
+    global _IS_PATCHED
+    if _IS_PATCHED:
+        return
+
+    try:
+        from behave.model import Table
+    except ImportError:
+        return
+
+    for name in _METHOD_NAMES:
+        if hasattr(Table, name):
+            _ORIGINAL_METHODS[name] = getattr(Table, name)
+        setattr(Table, name, _IMPLEMENTATIONS[name])
+
+    Table._behave_data_patched = True  # type: ignore[attr-defined]
+    _IS_PATCHED = True
+
+
+def revert_patches() -> None:
+    """Restore the original behave.model.Table methods.
+
+    This function is idempotent: calling it when not patched has no effect.
+    """
+    global _IS_PATCHED
+    if not _IS_PATCHED:
+        return
+
+    try:
+        from behave.model import Table
+    except ImportError:
+        return
+
+    for name in _METHOD_NAMES:
+        if name in _ORIGINAL_METHODS:
+            setattr(Table, name, _ORIGINAL_METHODS[name])
+        else:
+            if hasattr(Table, name):
+                delattr(Table, name)
+
+    if hasattr(Table, "_behave_data_patched"):
+        delattr(Table, "_behave_data_patched")
+
+    _ORIGINAL_METHODS.clear()
+    _IS_PATCHED = False