excel2api 1.0.0__py3-none-any.whl

excel2api/__init__.py

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

excel2api/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

excel2api/api.py

@@ -0,0 +1,98 @@
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+
+@dataclass
+class APIResult:
+    row: int
+    operation: str
+    success: bool
+    status_code: int | None = None
+    response: Any = None
+    error: str | None = None
+    sheet: str | None = None
+
+
+class APIClient:
+    RETRY_STATUS_CODES = (408, 429, 500, 502, 503, 504)
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        timeout: int = 30,
+        retries: int = 0,
+        retry_create: bool = False,
+        headers: dict[str, str] | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+
+        if token:
+            self.session.headers.update({"Authorization": f"Bearer {token}"})
+
+        self.session.headers.update({
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        })
+        if headers:
+            self.session.headers.update(headers)
+
+        if retries > 0:
+            allowed_methods = {"PUT", "PATCH", "DELETE", "GET", "HEAD", "OPTIONS"}
+            if retry_create:
+                allowed_methods.add("POST")
+
+            retry = Retry(
+                total=retries,
+                connect=retries,
+                read=retries,
+                status=retries,
+                backoff_factor=0.5,
+                status_forcelist=self.RETRY_STATUS_CODES,
+                allowed_methods=allowed_methods,
+                respect_retry_after_header=True,
+                raise_on_status=False,
+            )
+            adapter = HTTPAdapter(max_retries=retry)
+            self.session.mount("http://", adapter)
+            self.session.mount("https://", adapter)
+
+    def request(self, method: str, path: str = "", **kwargs):
+        url = f"{self.base_url}/{path.lstrip('/')}" if path else self.base_url
+        return self.session.request(method, url, timeout=self.timeout, **kwargs)
+
+    def execute(self, operation: str, record: dict, identifier=None, endpoints: dict[str, object] | None = None):
+        operation = operation.upper()
+        endpoints = endpoints or {}
+        default = {
+            "CREATE": {"method": "POST", "path": ""},
+            "UPDATE": {"method": "PUT", "path": "/{id}"},
+            "PATCH": {"method": "PATCH", "path": "/{id}"},
+            "DELETE": {"method": "DELETE", "path": "/{id}"},
+        }
+        if operation not in default and operation not in endpoints:
+            raise ValueError(f"Unsupported operation: {operation}")
+        spec = endpoints.get(operation, default.get(operation))
+        if isinstance(spec, str):
+            spec = {"method": default.get(operation, {"method": "POST"})["method"], "path": spec}
+        spec = spec or {}
+        method = str(spec.get("method", default.get(operation, {}).get("method", "POST"))).upper()
+        path_template = str(spec.get("path", default.get(operation, {}).get("path", "")))
+        if "{id}" in path_template or "{identifier}" in path_template:
+            if identifier is None:
+                raise ValueError(f"{operation} requires an identifier")
+        values = dict(record)
+        values.update({"id": identifier, "identifier": identifier})
+        try:
+            path = path_template.format(**values)
+        except KeyError as exc:
+            raise ValueError(f"Missing endpoint template field: {exc.args[0]}") from exc
+        if method == "DELETE":
+            return self.request(method, path)
+        return self.request(method, path, json=record)

excel2api/cli.py

@@ -0,0 +1,255 @@
+import json
+import os
+from pathlib import Path
+import typer
+
+from .converter import convert_file
+from .config import load_sync_config
+from .sync import sync_file
+from .schema import load_config
+from .report import write_error_report, write_sync_report
+from .dependencies import dependency_order, resolve_overrides
+from .doctor import validate_sync_config
+from . import __version__
+
+app = typer.Typer(help="Convert Excel/CSV into validated API-ready data.")
+
+
+@app.command()
+def doctor(
+    config: Path = typer.Argument(..., exists=True),
+):
+    """Validate a sync configuration before running a migration."""
+    try:
+        problems = validate_sync_config(config)
+    except Exception as exc:
+        typer.echo(f"ERROR: {exc}")
+        raise typer.Exit(code=2)
+    if problems:
+        typer.echo("Configuration check failed:")
+        for problem in problems:
+            typer.echo(f"- {problem}")
+        raise typer.Exit(code=2)
+    typer.echo(f"Excel2API {__version__}: configuration OK")
+
+
+@app.callback(invoke_without_command=True)
+def main(version: bool = typer.Option(False, "--version", help="Show version and exit.")):
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.command()
+def convert(
+    input_file: Path = typer.Argument(..., exists=True),
+    schema: Path = typer.Option(..., "--schema", "-s", exists=True),
+    output: Path | None = typer.Option(None, "--output", "-o"),
+):
+    """Validate and convert Excel/CSV data to JSON."""
+    records, errors = convert_file(str(input_file), str(schema))
+    if output:
+        output.write_text(json.dumps(records, indent=2, default=str), encoding="utf-8")
+        typer.echo(f"Output written to {output}")
+    else:
+        typer.echo(json.dumps(records, indent=2, default=str))
+    typer.echo(f"Valid records: {len(records)}")
+    typer.echo(f"Errors: {len(errors)}")
+    if errors:
+        for error in errors:
+            typer.echo(f"Row {error.row} | {error.field} | {error.message}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def validate(
+    input_file: Path = typer.Argument(..., exists=True),
+    schema: Path = typer.Option(..., "--schema", "-s", exists=True),
+):
+    """Validate Excel/CSV data without writing JSON output."""
+    records, errors = convert_file(str(input_file), str(schema))
+    typer.echo(f"Valid records: {len(records)}")
+    typer.echo(f"Errors: {len(errors)}")
+    for error in errors:
+        typer.echo(f"Row {error.row} | {error.field} | {error.message}")
+    if errors:
+        raise typer.Exit(code=1)
+
+
+def _parse_headers(items: list[str], configured: dict[str, str]) -> dict[str, str]:
+    headers = dict(configured or {})
+    for item in items:
+        if "=" not in item:
+            raise typer.BadParameter("Header must use NAME=VALUE format", param_hint="--header")
+        name, value = item.split("=", 1)
+        headers[name.strip()] = value
+    return headers
+
+
+def _auth_token(cfg_api: dict, token: str | None) -> str | None:
+    if token is not None:
+        return token
+    auth = cfg_api.get("auth", {}) or {}
+    auth_type = str(auth.get("type", "none")).lower()
+    if auth_type == "bearer":
+        token_env = auth.get("token_env", "EXCEL2API_TOKEN")
+        return os.getenv(token_env) or auth.get("token")
+    return os.getenv("EXCEL2API_TOKEN")
+
+
+@app.command()
+def sync(
+    input_file: Path | None = typer.Argument(None, exists=True),
+    schema: Path | None = typer.Option(None, "--schema", "-s", exists=True),
+    api: str | None = typer.Option(None, "--api"),
+    config: Path | None = typer.Option(None, "--config", "-c", exists=True),
+    operation_field: str | None = typer.Option(None, "--operation-field"),
+    identifier_field: str | None = typer.Option(None, "--id-field"),
+    token: str | None = typer.Option(None, "--token"),
+    dry_run: bool | None = typer.Option(None, "--dry-run/--no-dry-run"),
+    timeout: int | None = typer.Option(None, "--timeout", min=1),
+    retries: int | None = typer.Option(None, "--retries", min=0, max=10),
+    retry_create: bool | None = typer.Option(None, "--retry-create/--no-retry-create"),
+    report: Path | None = typer.Option(None, "--report"),
+    header: list[str] = typer.Option([], "--header"),
+    rate_limit: float | None = typer.Option(None, "--rate-limit", min=0.0),
+    batch_size: int | None = typer.Option(None, "--batch-size", min=0),
+    checkpoint: Path | None = typer.Option(None, "--checkpoint"),
+    resume: bool | None = typer.Option(None, "--resume/--no-resume"),
+    stop_on_error: bool | None = typer.Option(None, "--stop-on-error/--continue-on-error"),
+    excel_report: Path | None = typer.Option(None, "--excel-report"),
+    error_report: Path | None = typer.Option(None, "--error-report"),
+):
+    """Execute one or multiple Excel sheets against API endpoints."""
+    cfg = load_sync_config(str(config)) if config else {}
+    cfg_api = cfg.get("api", {}) or {}
+    cfg_sync = cfg.get("sync", {}) or {}
+
+    input_file = input_file or (Path(cfg["input"]) if cfg.get("input") else None)
+    schema = schema or (Path(cfg["schema"]) if cfg.get("schema") else None)
+    api = api or cfg_api.get("base_url")
+    if not input_file or not input_file.exists():
+        raise typer.BadParameter("Input file is required (argument or config.input)")
+    if not api and not cfg.get("sheets"):
+        raise typer.BadParameter("API URL is required (--api or config.api.base_url)")
+    if not schema and not cfg.get("sheets"):
+        raise typer.BadParameter("Schema file is required (--schema or config.schema)")
+
+    operation_field = operation_field or cfg_sync.get("operation_field", "operation")
+    identifier_field = identifier_field or cfg_sync.get("identifier_field", "id")
+    timeout = timeout if timeout is not None else int(cfg_api.get("timeout", 30))
+    retries = retries if retries is not None else int(cfg_api.get("retries", 0))
+    retry_create = retry_create if retry_create is not None else bool(cfg_api.get("retry_create", False))
+    rate_limit = rate_limit if rate_limit is not None else float(cfg_api.get("rate_limit", 0.0))
+    batch_size = batch_size if batch_size is not None else int(cfg_sync.get("batch_size", 0))
+    resume = resume if resume is not None else bool(cfg_sync.get("resume", False))
+    stop_on_error = stop_on_error if stop_on_error is not None else bool(cfg_sync.get("stop_on_error", False))
+    dry_run = dry_run if dry_run is not None else bool(cfg_sync.get("dry_run", False))
+    checkpoint = checkpoint or (Path(cfg_sync["checkpoint"]) if cfg_sync.get("checkpoint") else None)
+    report = report or (Path(cfg_sync["report"]) if cfg_sync.get("report") else None)
+    excel_report = excel_report or (Path(cfg_sync["excel_report"]) if cfg_sync.get("excel_report") else None)
+    error_report = error_report or (Path(cfg_sync["error_report"]) if cfg_sync.get("error_report") else None)
+    headers = _parse_headers(header, cfg_api.get("headers", {}))
+    token = _auth_token(cfg_api, token)
+
+    sheets = cfg.get("sheets") or {}
+    jobs = []
+    if sheets:
+        for sheet_name, sheet_cfg in sheets.items():
+            sheet_cfg = sheet_cfg or {}
+            sheet_schema = Path(sheet_cfg["schema"])
+            sheet_api = str(api or cfg_api.get("base_url", "")).rstrip("/")
+            endpoint = sheet_cfg.get("endpoint")
+            if endpoint:
+                sheet_api += "/" + str(endpoint).lstrip("/")
+            jobs.append((sheet_name, sheet_schema, sheet_api, sheet_cfg))
+    else:
+        jobs.append((None, schema, api, {}))
+
+    # Resolve multi-sheet dependencies before execution. Sheets without references
+    # retain their configured order; dependencies are topologically sorted.
+    if sheets:
+        ordered_names = dependency_order(sheets)
+        jobs_by_name = {job[0]: job for job in jobs}
+        jobs = [jobs_by_name[name] for name in ordered_names]
+        for name, _, _, cfg_item in jobs:
+            cfg_item["_all_sheets"] = sheets
+
+    all_results = []
+    all_errors = []
+    results_by_sheet = {}
+    for sheet_name, job_schema, job_api, sheet_cfg in jobs:
+        if not job_schema.exists():
+            raise typer.BadParameter(f"Schema file not found for sheet '{sheet_name}': {job_schema}")
+        job_sync = sheet_cfg.get("sync", {}) or {}
+        job_endpoints = sheet_cfg.get("endpoints", cfg_api.get("endpoints", {})) or {}
+        job_operation = sheet_cfg.get("operation_field", job_sync.get("operation_field", operation_field))
+        job_identifier = sheet_cfg.get("identifier_field", job_sync.get("identifier_field", identifier_field))
+        job_response = sheet_cfg.get("response", cfg.get("response", {})) or {}
+        job_mapping = job_response.get("mapping", {}) or {}
+        job_checkpoint = sheet_cfg.get("checkpoint")
+        if job_checkpoint is None:
+            job_checkpoint = str(checkpoint) if checkpoint and not sheets else None
+        job_resume = bool(sheet_cfg.get("resume", resume))
+        job_batch = int(sheet_cfg.get("batch_size", batch_size))
+
+        overrides = {}
+        if sheet_name:
+            overrides = resolve_overrides(str(input_file), sheet_name, sheet_cfg, results_by_sheet)
+
+        results, errors = sync_file(
+            str(input_file), str(job_schema), job_api,
+            operation_field=job_operation, identifier_field=job_identifier,
+            token=token, dry_run=bool(sheet_cfg.get("dry_run", dry_run)),
+            timeout=int(sheet_cfg.get("timeout", timeout)), retries=int(sheet_cfg.get("retries", retries)),
+            retry_create=bool(sheet_cfg.get("retry_create", retry_create)), headers=headers,
+            rate_limit=float(sheet_cfg.get("rate_limit", rate_limit)), batch_size=job_batch,
+            checkpoint=job_checkpoint, resume=job_resume,
+            stop_on_error=bool(sheet_cfg.get("stop_on_error", stop_on_error)),
+            response_mapping=job_mapping, endpoints=job_endpoints, sheet_name=sheet_name,
+            record_overrides=overrides,
+        )
+        for r in results:
+            r.sheet = sheet_name
+        for e in errors:
+            e.sheet = sheet_name
+        all_results.extend(results)
+        all_errors.extend(errors)
+        if sheet_name:
+            results_by_sheet[sheet_name] = results
+        typer.echo(f"Sheet: {sheet_name or 'default'} | processed: {len(results)} | validation errors: {len(errors)}")
+
+    if all_errors:
+        if error_report:
+            write_error_report(error_report, all_errors)
+            typer.echo(f"Error report written to {error_report}")
+        for error in all_errors:
+            typer.echo(f"Sheet {getattr(error, 'sheet', None)} | Row {error.row} | {error.field} | {error.message}")
+        raise typer.Exit(code=1)
+
+    counts, failures = {}, 0
+    for result in all_results:
+        counts[result.operation] = counts.get(result.operation, 0) + 1
+        failures += int(not result.success)
+        status = "OK" if result.success else "FAILED"
+        detail = f"HTTP {result.status_code}" if result.status_code is not None else result.error or "DRY RUN"
+        typer.echo(f"Sheet {getattr(result, 'sheet', None) or 'default'} | Row {result.row} | {result.operation} | {status} | {detail}")
+
+    typer.echo("\nSummary")
+    typer.echo(f"Total: {len(all_results)}")
+    for operation, count in sorted(counts.items()):
+        typer.echo(f"{operation}: {count}")
+    typer.echo(f"Failed: {failures}")
+
+    if report:
+        data = [{"sheet": getattr(r, "sheet", None), "row": r.row, "operation": r.operation,
+                 "success": r.success, "status_code": r.status_code, "response": r.response,
+                 "error": r.error} for r in all_results]
+        report.write_text(json.dumps({"results": data, "summary": {"total": len(data), "failed": failures}}, indent=2, default=str), encoding="utf-8")
+        typer.echo(f"Report written to {report}")
+    if excel_report:
+        # Response mappings can differ per sheet; use a generic combined report.
+        write_sync_report(excel_report, all_results)
+        typer.echo(f"Excel report written to {excel_report}")
+    if failures:
+        raise typer.Exit(code=1)

excel2api/config.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+import yaml
+
+
+def load_sync_config(path: str | Path) -> dict:
+    """Load and validate a sync configuration file."""
+    with open(path, "r", encoding="utf-8") as file:
+        data = yaml.safe_load(file) or {}
+
+    if not isinstance(data, dict):
+        raise ValueError("Sync config must be a YAML mapping")
+
+    for section in ("api", "sync", "response"):
+        value = data.get(section, {}) or {}
+        if not isinstance(value, dict):
+            raise ValueError(f"{section} section must be a mapping")
+
+    sheets = data.get("sheets", {}) or {}
+    if sheets and not isinstance(sheets, dict):
+        raise ValueError("sheets section must be a mapping")
+    for name, spec in sheets.items():
+        if not isinstance(spec, dict):
+            raise ValueError(f"Sheet '{name}' configuration must be a mapping")
+        if not spec.get("schema"):
+            raise ValueError(f"Sheet '{name}' must define a schema")
+        refs = spec.get("references", []) or []
+        if not isinstance(refs, list):
+            raise ValueError(f"Sheet '{name}' references must be a list")
+
+    return data

excel2api/converter.py

@@ -0,0 +1,18 @@
+from .reader import read_file
+from .schema import load_schema
+from .validator import validate_and_convert
+
+
+def convert_file(input_path: str, schema_path: str, sheet_name=None):
+    rows = read_file(input_path, sheet_name=sheet_name)
+    fields = load_schema(schema_path)
+
+    records = []
+    errors = []
+    for row_number, row in enumerate(rows, start=2):
+        record, row_errors = validate_and_convert(row, fields, row_number)
+        if row_errors:
+            errors.extend(row_errors)
+        else:
+            records.append(record)
+    return records, errors

excel2api/dependencies.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .report import extract_path
+from .schema import load_schema
+
+
+@dataclass(frozen=True)
+class ReferenceSpec:
+    target_field: str
+    source_sheet: str
+    source_key: str
+    target_key: str
+    source_value: str
+
+
+def parse_references(sheet_cfg: dict[str, Any]) -> list[ReferenceSpec]:
+    refs = sheet_cfg.get("references", []) or []
+    if not isinstance(refs, list):
+        raise ValueError("references must be a list")
+    result = []
+    for ref in refs:
+        if not isinstance(ref, dict):
+            raise ValueError("each reference must be a mapping")
+        required = ("target_field", "source_sheet", "source_key", "target_key", "source_value")
+        missing = [key for key in required if not ref.get(key)]
+        if missing:
+            raise ValueError(f"reference missing required fields: {', '.join(missing)}")
+        result.append(ReferenceSpec(**{key: ref[key] for key in required}))
+    return result
+
+
+def dependency_order(sheets: dict[str, dict[str, Any]]) -> list[str]:
+    graph = {name: set() for name in sheets}
+    for name, cfg in sheets.items():
+        for ref in parse_references(cfg or {}):
+            if ref.source_sheet not in sheets:
+                raise ValueError(f"Sheet '{name}' references unknown sheet '{ref.source_sheet}'")
+            if ref.source_sheet == name:
+                raise ValueError(f"Sheet '{name}' cannot depend on itself")
+            graph[name].add(ref.source_sheet)
+
+    ordered = []
+    remaining = {name: set(deps) for name, deps in graph.items()}
+    while remaining:
+        ready = sorted(name for name, deps in remaining.items() if not deps)
+        if not ready:
+            cycle = ", ".join(sorted(remaining))
+            raise ValueError(f"Circular sheet dependency detected involving: {cycle}")
+        ordered.extend(ready)
+        for name in ready:
+            remaining.pop(name)
+        for deps in remaining.values():
+            deps.difference_update(ready)
+    return ordered
+
+
+def build_reference_indexes(
+    sheet_name: str,
+    results: list[Any],
+    response_mapping: dict[str, str],
+) -> dict[str, dict[Any, Any]]:
+    indexes: dict[str, dict[Any, Any]] = {}
+    for result in results:
+        if not result.success or not result.record:
+            continue
+        for key_name in {
+            key for key in result.record.keys()
+        }:
+            indexes.setdefault(key_name, {})[result.record.get(key_name)] = result.response
+    return indexes
+
+
+def resolve_overrides(
+    input_path: str,
+    sheet_name: str,
+    sheet_cfg: dict[str, Any],
+    results_by_sheet: dict[str, list[Any]],
+) -> dict[int, dict[str, Any]]:
+    """Build row-numbered target-field overrides from completed dependency sheets."""
+    refs = parse_references(sheet_cfg)
+    if not refs:
+        return {}
+
+    target_fields = {f.name: f.column for f in load_schema(sheet_cfg["schema"])}
+    all_rows = __import__("excel2api.reader", fromlist=["read_file"]).read_file(input_path, sheet_name=sheet_name)
+    overrides: dict[int, dict[str, Any]] = {}
+
+    for ref in refs:
+        if ref.target_field not in target_fields:
+            raise ValueError(f"Reference target field '{ref.target_field}' is not in sheet '{sheet_name}' schema")
+        source_results = results_by_sheet.get(ref.source_sheet)
+        if source_results is None:
+            raise ValueError(f"Dependency '{ref.source_sheet}' has not been processed")
+
+        source_map: dict[Any, Any] = {}
+        source_mapping = {}
+        # Read the dependency's configured response mapping if present.
+        source_cfg = sheet_cfg.get("_all_sheets", {}).get(ref.source_sheet, {}) if isinstance(sheet_cfg.get("_all_sheets"), dict) else {}
+        source_mapping = (source_cfg.get("response", {}) or {}).get("mapping", {}) or {}
+        if ref.source_value in source_mapping:
+            response_path = source_mapping[ref.source_value]
+        else:
+            response_path = ref.source_value
+
+        for result in source_results:
+            if not result.success or not result.record:
+                continue
+            key = result.record.get(ref.source_key)
+            value = extract_path(result.response, response_path, None)
+            if key is not None and value is not None:
+                source_map[key] = value
+
+        for row_number, raw_row in enumerate(all_rows, start=2):
+            target_key = raw_row.get(target_fields.get(ref.target_key, ref.target_key))
+            if target_key in source_map:
+                overrides.setdefault(row_number, {})[ref.target_field] = source_map[target_key]
+    return overrides

excel2api/doctor.py

@@ -0,0 +1,79 @@
+from pathlib import Path
+from typing import Any
+
+from .config import load_sync_config
+from .reader import list_sheets
+from .schema import load_schema
+from .dependencies import dependency_order
+
+
+def validate_sync_config(path: str | Path) -> list[str]:
+    """Return configuration problems; an empty list means the config is healthy."""
+    config_path = Path(path).resolve()
+    cfg = load_sync_config(config_path)
+    problems: list[str] = []
+    base = config_path.parent
+
+    def resolve(value: Any) -> Path:
+        p = Path(str(value))
+        return p if p.is_absolute() else base / p
+
+    input_value = cfg.get("input")
+    if input_value:
+        input_path = resolve(input_value)
+        if not input_path.exists():
+            problems.append(f"Input file not found: {input_path}")
+        elif input_path.suffix.lower() not in {".xlsx", ".xls", ".csv"}:
+            problems.append(f"Unsupported input format: {input_path.suffix}")
+    elif not cfg.get("sheets"):
+        problems.append("Missing config.input")
+
+    api = cfg.get("api", {}) or {}
+    if not api.get("base_url") and not cfg.get("sheets"):
+        problems.append("Missing api.base_url")
+
+    sheets = cfg.get("sheets", {}) or {}
+    try:
+        dependency_order(sheets)
+    except ValueError as exc:
+        problems.append(str(exc))
+
+    for sheet_name, spec in sheets.items():
+        schema_path = resolve(spec.get("schema", ""))
+        if not schema_path.exists():
+            problems.append(f"Schema for sheet '{sheet_name}' not found: {schema_path}")
+        else:
+            try:
+                load_schema(schema_path)
+            except Exception as exc:
+                problems.append(f"Invalid schema for sheet '{sheet_name}': {exc}")
+        if input_value and Path(str(input_value)).suffix.lower() in {".xlsx", ".xls"}:
+            try:
+                names = list_sheets(resolve(input_value))
+                if sheet_name not in names:
+                    problems.append(f"Sheet '{sheet_name}' not found in workbook")
+            except Exception as exc:
+                problems.append(f"Cannot inspect workbook: {exc}")
+
+    if not sheets and cfg.get("schema"):
+        schema_path = resolve(cfg["schema"])
+        if not schema_path.exists():
+            problems.append(f"Schema file not found: {schema_path}")
+        else:
+            try:
+                load_schema(schema_path)
+            except Exception as exc:
+                problems.append(f"Invalid schema: {exc}")
+    elif not sheets and not cfg.get("schema"):
+        problems.append("Missing config.schema")
+
+    for operation, spec in (api.get("endpoints", {}) or {}).items():
+        if not isinstance(spec, (str, dict)):
+            problems.append(f"Endpoint '{operation}' must be a string or mapping")
+            continue
+        if isinstance(spec, dict) and not spec.get("method"):
+            problems.append(f"Endpoint '{operation}' is missing method")
+        if isinstance(spec, dict) and "path" not in spec:
+            problems.append(f"Endpoint '{operation}' is missing path")
+
+    return problems

excel2api/errors.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ValidationError:
+    row: int
+    field: str
+    message: str
+    sheet: str | None = None
+
+    def as_dict(self) -> dict:
+        return {
+            "row": self.row,
+            "field": self.field,
+            "message": self.message,
+            "sheet": self.sheet,
+        }

excel2api/reader.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+import pandas as pd
+
+SUPPORTED_EXTENSIONS = {".xlsx", ".xls", ".csv"}
+
+
+def _validate_path(path: str | Path) -> Path:
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Input file not found: {path}")
+    if path.suffix.lower() not in SUPPORTED_EXTENSIONS:
+        raise ValueError(
+            f"Unsupported file type: {path.suffix}. "
+            f"Supported: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+        )
+    return path
+
+
+def list_sheets(path: str | Path) -> list[str]:
+    path = _validate_path(path)
+    if path.suffix.lower() == ".csv":
+        return ["CSV"]
+    return list(pd.ExcelFile(path).sheet_names)
+
+
+def read_file(path: str | Path, sheet_name: str | int | None = None) -> list[dict]:
+    path = _validate_path(path)
+    if path.suffix.lower() == ".csv":
+        if sheet_name not in (None, "CSV"):
+            raise ValueError("CSV files do not contain multiple sheets")
+        frame = pd.read_csv(path)
+    else:
+        frame = pd.read_excel(path, sheet_name=sheet_name if sheet_name is not None else 0)
+
+    frame = frame.where(pd.notna(frame), None)
+    return frame.to_dict(orient="records")