excel2api 1.0.0__py3-none-any.whl

excel2api/report.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+from typing import Any
+
+from openpyxl import Workbook
+
+
+def extract_path(data: Any, path: str, default=None):
+    """Extract a dotted path from a JSON-like response."""
+    if not path:
+        return default
+    current = data
+    for part in path.split('.'):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return default
+    return current
+
+
+def write_error_report(path: str | Path, errors: list[Any]):
+    workbook = Workbook()
+    sheet = workbook.active
+    sheet.title = "Errors"
+    sheet.append(["Sheet", "Row", "Field", "Message"])
+    for error in errors:
+        sheet.append([getattr(error, "sheet", ""), error.row, error.field, error.message])
+    workbook.save(path)
+
+
+def write_sync_report(path: str | Path, results: list[Any], response_mapping: dict[str, str] | None = None):
+    workbook = Workbook()
+    sheet = workbook.active
+    sheet.title = "Sync Results"
+
+    mapping = response_mapping or {}
+    headers = ["Sheet", "Row", "Operation", "Success", "HTTP Status", "Error"] + list(mapping.keys())
+    sheet.append(headers)
+
+    for result in results:
+        values = [getattr(result, "sheet", ""), result.row, result.operation, result.success, result.status_code, result.error]
+        for output_name, response_path in mapping.items():
+            values.append(extract_path(result.response, response_path, ""))
+        sheet.append(values)
+
+    workbook.save(path)

excel2api/schema.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+import yaml
+
+
+SUPPORTED_TYPES = {
+    "string", "integer", "float", "decimal",
+    "boolean", "date", "datetime", "email", "phone"
+}
+
+
+@dataclass
+class Field:
+    name: str
+    column: str
+    type: str = "string"
+    required: bool = False
+    nullable: bool = True
+    default: object = None
+    options: list[object] = field(default_factory=list)
+    min_length: int | None = None
+    max_length: int | None = None
+    minimum: float | None = None
+    maximum: float | None = None
+    regex: str | None = None
+    transform: list[str] = field(default_factory=list)
+    include: bool = True
+
+
+def load_config(path: str | Path) -> dict:
+    with open(path, "r", encoding="utf-8") as file:
+        data = yaml.safe_load(file) or {}
+
+    fields = []
+    for name, config in data.get("fields", {}).items():
+        config = config or {}
+        field_type = config.get("type", "string")
+
+        if field_type not in SUPPORTED_TYPES:
+            raise ValueError(
+                f"Unsupported type '{field_type}' for field '{name}'. "
+                f"Supported types: {', '.join(sorted(SUPPORTED_TYPES))}"
+            )
+
+        fields.append(Field(
+            name=name,
+            column=config.get("column", name),
+            type=field_type,
+            required=config.get("required", False),
+            nullable=config.get("nullable", True),
+            default=config.get("default"),
+            options=config.get("options", []),
+            min_length=config.get("min_length"),
+            max_length=config.get("max_length"),
+            minimum=config.get("min"),
+            maximum=config.get("max"),
+            regex=config.get("regex"),
+            transform=config.get("transform", []),
+            include=config.get("include", True),
+        ))
+
+    if not fields:
+        raise ValueError("Schema must contain at least one field")
+
+    return {"fields": fields, "response": data.get("response", {}) or {}}
+
+
+def load_schema(path: str | Path) -> list[Field]:
+    return load_config(path)["fields"]

excel2api/sync.py

@@ -0,0 +1,154 @@
+import json
+from pathlib import Path
+import time
+
+from .api import APIClient, APIResult
+from .converter import convert_file
+from .reader import read_file
+from .schema import load_config
+
+
+SUPPORTED_OPERATIONS = {"CREATE", "UPDATE", "PATCH", "DELETE", "UPSERT"}
+
+
+def _save_checkpoint(path: str | Path, completed_rows: set[int]):
+    path = Path(path)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps({"completed_rows": sorted(completed_rows)}, indent=2), encoding="utf-8")
+    tmp.replace(path)
+
+
+def _load_checkpoint(path: str | Path) -> set[int]:
+    path = Path(path)
+    if not path.exists():
+        return set()
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return {int(row) for row in data.get("completed_rows", [])}
+
+
+def sync_file(
+    input_path: str,
+    schema_path: str,
+    api_url: str,
+    operation_field: str = "operation",
+    identifier_field: str = "id",
+    token: str | None = None,
+    dry_run: bool = False,
+    timeout: int = 30,
+    retries: int = 0,
+    retry_create: bool = False,
+    headers: dict[str, str] | None = None,
+    rate_limit: float = 0.0,
+    batch_size: int = 0,
+    checkpoint: str | None = None,
+    resume: bool = False,
+    stop_on_error: bool = False,
+    response_mapping: dict[str, str] | None = None,
+    endpoints: dict[str, object] | None = None,
+    sheet_name: str | int | None = None,
+    record_overrides: dict[int, dict] | None = None,
+):
+    records, errors = convert_file(input_path, schema_path, sheet_name=sheet_name)
+    if errors:
+        return [], errors
+
+    rows = read_file(input_path, sheet_name=sheet_name)
+    record_overrides = record_overrides or {}
+    if record_overrides:
+        # Re-validate with dependency-provided values before API execution.
+        from .schema import load_schema
+        from .validator import validate_and_convert
+        fields = load_schema(schema_path)
+        records = []
+        errors = []
+        for row_number, raw_row in enumerate(rows, start=2):
+            merged = dict(raw_row)
+            for field_name, value in record_overrides.get(row_number, {}).items():
+                for field in fields:
+                    if field.name == field_name:
+                        merged[field.column] = value
+                        break
+            record, row_errors = validate_and_convert(merged, fields, row_number)
+            if row_errors:
+                errors.extend(row_errors)
+            else:
+                records.append(record)
+        if errors:
+            return [], errors
+
+    client = APIClient(
+        api_url,
+        token=token,
+        timeout=timeout,
+        retries=retries,
+        retry_create=retry_create,
+        headers=headers,
+    )
+    results = []
+    completed_rows = _load_checkpoint(checkpoint) if (resume and checkpoint) else set()
+    processed_since_checkpoint = 0
+
+    for index, (row, record) in enumerate(zip(rows, records), start=2):
+        if index in completed_rows:
+            continue
+
+        operation = str(row.get(operation_field) or "CREATE").upper()
+        identifier = row.get(identifier_field)
+
+        if operation not in SUPPORTED_OPERATIONS:
+            result = APIResult(row=index, operation=operation, success=False,
+                               error=f"unsupported operation: {operation}", record=record)
+            results.append(result)
+            if stop_on_error:
+                break
+            continue
+
+        if dry_run:
+            result = APIResult(row=index, operation=operation, success=True,
+                               response={"dry_run": True, "record": record, "id": identifier}, record=record)
+        else:
+            try:
+                if operation == "UPSERT":
+                    if identifier is None:
+                        raise ValueError("UPSERT requires an identifier")
+                    response = client.execute("PATCH", record, identifier, endpoints=endpoints)
+                else:
+                    response = client.execute(operation, record, identifier, endpoints=endpoints)
+
+                try:
+                    response_body = response.json()
+                except ValueError:
+                    response_body = response.text
+
+                result = APIResult(
+                    row=index,
+                    operation=operation,
+                    success=response.ok,
+                    status_code=response.status_code,
+                    response=response_body,
+                    error=None if response.ok else f"HTTP {response.status_code}",
+                    record=record,
+                )
+            except Exception as exc:
+                result = APIResult(row=index, operation=operation, success=False, error=str(exc), record=record)
+
+        results.append(result)
+        processed_since_checkpoint += 1
+
+        if result.success:
+            completed_rows.add(index)
+
+        if checkpoint and (processed_since_checkpoint >= batch_size if batch_size > 0 else True):
+            _save_checkpoint(checkpoint, completed_rows)
+            processed_since_checkpoint = 0
+
+        if stop_on_error and not result.success:
+            break
+
+        if rate_limit > 0 and index < len(rows) + 1:
+            time.sleep(rate_limit)
+
+    if checkpoint:
+        _save_checkpoint(checkpoint, completed_rows)
+
+    return results, []

excel2api/validator.py

@@ -0,0 +1,160 @@
+import re
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+from .errors import ValidationError
+
+
+EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+PHONE_RE = re.compile(r"^\+?[0-9][0-9\s-]{6,19}$")
+
+
+def is_empty(value):
+    return value is None or (isinstance(value, str) and not value.strip())
+
+
+def convert(value, field_type):
+    if value is None:
+        return None
+
+    if field_type == "string":
+        return str(value).strip()
+
+    if field_type == "integer":
+        return int(value)
+
+    if field_type == "float":
+        return float(value)
+
+    if field_type == "decimal":
+        return float(Decimal(str(value)))
+
+    if field_type == "boolean":
+        if isinstance(value, bool):
+            return value
+        normalized = str(value).strip().lower()
+        if normalized in {"true", "yes", "1"}:
+            return True
+        if normalized in {"false", "no", "0"}:
+            return False
+        raise ValueError("must be a boolean")
+
+    if field_type == "date":
+        if isinstance(value, datetime):
+            return value.strftime("%Y-%m-%d")
+        if isinstance(value, date):
+            return value.strftime("%Y-%m-%d")
+        return datetime.fromisoformat(str(value)).date().isoformat()
+
+    if field_type == "datetime":
+        if isinstance(value, datetime):
+            return value.isoformat()
+        return datetime.fromisoformat(str(value)).isoformat()
+
+    if field_type in {"email", "phone"}:
+        return str(value).strip()
+
+    raise ValueError(f"unsupported type: {field_type}")
+
+
+def apply_transforms(value, transforms):
+    for transform in transforms:
+        if value is None:
+            break
+        if transform == "strip":
+            value = str(value).strip()
+        elif transform == "uppercase":
+            value = str(value).upper()
+        elif transform == "lowercase":
+            value = str(value).lower()
+        else:
+            raise ValueError(f"unknown transform: {transform}")
+    return value
+
+
+def validate_and_convert(row: dict, fields: list[object], row_number: int):
+    output = {}
+    errors = []
+
+    for field in fields:
+        value = row.get(field.column)
+
+        if is_empty(value):
+            if field.required:
+                errors.append(ValidationError(
+                    row_number, field.name, "required field is missing"
+                ))
+                continue
+
+            if field.default is not None:
+                value = field.default
+            elif field.nullable:
+                output[field.name] = None
+                continue
+            else:
+                errors.append(ValidationError(
+                    row_number, field.name, "null value is not allowed"
+                ))
+                continue
+
+        try:
+            value = apply_transforms(value, field.transform)
+            value = convert(value, field.type)
+        except (ValueError, TypeError, InvalidOperation, OverflowError) as exc:
+            errors.append(ValidationError(row_number, field.name, str(exc)))
+            continue
+
+        if field.type == "email" and not EMAIL_RE.match(value):
+            errors.append(ValidationError(
+                row_number, field.name, "invalid email address"
+            ))
+            continue
+
+        if field.type == "phone" and not PHONE_RE.match(value):
+            errors.append(ValidationError(
+                row_number, field.name, "invalid phone number"
+            ))
+            continue
+
+        if field.min_length is not None and len(value) < field.min_length:
+            errors.append(ValidationError(
+                row_number, field.name,
+                f"length must be at least {field.min_length}"
+            ))
+            continue
+
+        if field.max_length is not None and len(value) > field.max_length:
+            errors.append(ValidationError(
+                row_number, field.name,
+                f"length must be at most {field.max_length}"
+            ))
+            continue
+
+        if field.minimum is not None and value < field.minimum:
+            errors.append(ValidationError(
+                row_number, field.name, f"value must be >= {field.minimum}"
+            ))
+            continue
+
+        if field.maximum is not None and value > field.maximum:
+            errors.append(ValidationError(
+                row_number, field.name, f"value must be <= {field.maximum}"
+            ))
+            continue
+
+        if field.options and value not in field.options:
+            errors.append(ValidationError(
+                row_number, field.name,
+                f"must be one of: {', '.join(map(str, field.options))}"
+            ))
+            continue
+
+        if field.regex and not re.fullmatch(field.regex, str(value)):
+            errors.append(ValidationError(
+                row_number, field.name, "does not match required pattern"
+            ))
+            continue
+
+        if field.include:
+            output[field.name] = value
+
+    return output, errors