api-chain-runner 1.0.0__py3-none-any.whl

api_chain_runner/__init__.py

@@ -0,0 +1,18 @@
+"""API Chain Runner — execute chained API calls with dynamic reference resolution."""
+
+__version__ = "1.0.0"
+
+from api_chain_runner.runner import ChainRunner
+from api_chain_runner.models import (
+    ChainResult,
+    ConfigurationError,
+    StepResult,
+)
+
+__all__ = [
+    "__version__",
+    "ChainRunner",
+    "ChainResult",
+    "ConfigurationError",
+    "StepResult",
+]

api_chain_runner/__main__.py

@@ -0,0 +1,138 @@
+"""CLI entry point for API Chain Runner.
+
+Usage::
+
+    python -m api_chain_runner example_chain.yaml
+    python -m api_chain_runner example_chain.yaml -o results.csv
+    python -m api_chain_runner example_chain.yaml -o results.xlsx -f xlsx
+"""
+
+from __future__ import annotations
+import argparse
+import os
+import re
+import yaml
+from api_chain_runner import __version__
+from api_chain_runner.logger import ResultLogger
+from api_chain_runner.runner import ChainRunner
+
+
+def _substitute_env_vars(obj):
+    """Recursively substitute ``${ENV:VAR_NAME}`` placeholders with
+    the corresponding environment variable values.
+
+    If the environment variable is not set the placeholder is left as-is
+    so the user gets a clear signal that something is missing.
+    """
+    if isinstance(obj, dict):
+        return {k: _substitute_env_vars(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_substitute_env_vars(item) for item in obj]
+    if isinstance(obj, str):
+        def _replace(match):
+            var_name = match.group(1)
+            return os.environ.get(var_name, match.group(0))
+        return re.sub(r"\$\{ENV:([^}]+)\}", _replace, obj)
+    return obj
+
+
+def _preprocess_config(config_path: str) -> str:
+    """Read a YAML config, perform env-var substitution, and write to a
+    temporary file so that :class:`ChainRunner` can load it normally.
+
+    Returns the path to the (possibly rewritten) config file.
+    """
+    with open(config_path, "r", encoding="utf-8") as fh:
+        raw = yaml.safe_load(fh)
+
+    substituted = _substitute_env_vars(raw)
+
+    # If nothing changed we can just use the original file directly.
+    if substituted == raw:
+        return config_path
+
+    import tempfile
+
+    tmp = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".yaml", delete=False, encoding="utf-8"
+    )
+    yaml.dump(substituted, tmp, default_flow_style=False)
+    tmp.close()
+    return tmp.name
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="api_chain_runner",
+        description="Execute a chain of API calls defined in a YAML config file.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "config",
+        help="Path to the YAML chain configuration file.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="Output file path for results (default: <config_stem>_results.csv).",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=["csv", "xlsx"],
+        default="csv",
+        help="Output format: csv (default) or xlsx.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse arguments, run the chain, and print a summary."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # Pre-process config to resolve ${ENV:...} placeholders
+    processed_config = _preprocess_config(args.config)
+
+    try:
+        runner = ChainRunner(processed_config)
+
+        # Override output path / format if the user specified them
+        if args.output or args.format != "csv":
+            output_path = args.output or runner.logger._output_path
+            runner.logger = ResultLogger(str(output_path), fmt=args.format)
+            # Re-wire the executor's logger reference
+            runner.executor.logger = runner.logger
+
+        result = runner.run()
+    finally:
+        # Clean up temp file if we created one
+        if processed_config != args.config:
+            import os as _os
+
+            try:
+                _os.unlink(processed_config)
+            except OSError:
+                pass
+
+    # Print summary to stdout
+    print(
+        f"Executed {result.total_steps} steps: "
+        f"{result.passed} passed, {result.failed} failed"
+    )
+    for step_result in result.results:
+        status = "\u2713" if step_result.success else "\u2717"
+        print(
+            f"  {status} {step_result.step_name} \u2014 "
+            f"HTTP {step_result.status_code} ({step_result.duration_ms:.0f}ms)"
+        )
+
+
+if __name__ == "__main__":
+    main()

api_chain_runner/executor.py

@@ -0,0 +1,285 @@
+"""StepExecutor — executes a single API step with reference resolution and logging."""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import time
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+import requests
+from api_chain_runner.generator import UniqueDataGenerator
+from api_chain_runner.logger import ResultLogger
+from api_chain_runner.models import LogEntry, StepDefinition, StepResult
+from api_chain_runner.pause import PauseController
+from api_chain_runner.resolver import ReferenceResolver
+from api_chain_runner.store import ResponseStore
+
+IST = timezone(timedelta(hours=5, minutes=30))
+
+
+class StepExecutor:
+    """Executes a single API step: resolve references, generate unique data,
+    make the HTTP call, store the response, and log the result.
+
+    Parameters
+    ----------
+    resolver:
+        Resolves ``${step.key}`` references against stored responses.
+    generator:
+        Generates unique values for marked fields.
+    store:
+        In-memory response store for cross-step data sharing.
+    logger:
+        Logs every request/response to CSV or Excel.
+    pause_controller:
+        Optional controller for pause/resume during polling.
+    """
+
+    def __init__(
+        self,
+        resolver: ReferenceResolver,
+        generator: UniqueDataGenerator,
+        store: ResponseStore,
+        logger: ResultLogger,
+        pause_controller: PauseController | None = None,
+    ) -> None:
+        self.resolver = resolver
+        self.generator = generator
+        self.store = store
+        self.logger = logger
+        self.pause_controller = pause_controller
+
+    def execute(self, step: StepDefinition) -> StepResult:
+        """Execute a step, with optional polling until expected value is found.
+
+        If the step has a ``polling`` config, the step is re-executed at the
+        configured intervals until the response contains the expected value
+        at the specified key path, or the max timeout is exceeded.
+
+        Only the final polling result is logged to CSV — intermediate attempts
+        are printed to console but not written to the log file.
+        """
+        if not step.polling:
+            return self._execute_once(step)
+
+        polling = step.polling
+        start_time = time.monotonic()
+        attempt = 0
+
+        while True:
+            # Check for pause before each poll attempt
+            if self.pause_controller:
+                self.pause_controller.wait_if_paused()
+
+            result = self._execute_once(step, log_to_csv=False)
+            attempt += 1
+
+            # Subtract paused time from elapsed so timeout doesn't tick while paused
+            paused_time = self.pause_controller.total_paused if self.pause_controller else 0.0
+            elapsed = time.monotonic() - start_time - paused_time
+
+            # Check if the response value matches any of the expected values
+            if result.success and isinstance(result.response_body, dict):
+                actual = self._get_nested(result.response_body, polling.key_path)
+                if str(actual) in polling.expected_values:
+                    print(
+                        f"  [polling] '{step.name}' got expected "
+                        f"'{polling.key_path}={actual}' "
+                        f"after {attempt} attempt(s) ({elapsed:.1f}s)"
+                    )
+                    self._log_result(step, result)
+                    return result
+                else:
+                    print(
+                        f"  [polling] '{step.name}' attempt {attempt}: "
+                        f"'{polling.key_path}' = '{actual}' "
+                        f"(waiting for {polling.expected_values})"
+                    )
+
+            # Check timeout before sleeping for next attempt
+            if elapsed >= polling.max_timeout:
+                actual_display = self._get_nested(
+                    result.response_body, polling.key_path
+                ) if isinstance(result.response_body, dict) else "N/A"
+                error_msg = (
+                    f"Polling timed out after {elapsed:.1f}s ({attempt} attempts). "
+                    f"Expected '{polling.key_path}' in {polling.expected_values}, "
+                    f"last value='{actual_display}'."
+                )
+                print(f"  [polling] '{step.name}' TIMEOUT: {error_msg}")
+                timeout_result = StepResult(
+                    step_name=step.name,
+                    status_code=result.status_code,
+                    response_body=result.response_body,
+                    duration_ms=(time.monotonic() - start_time - paused_time) * 1000,
+                    success=False,
+                    error=error_msg,
+                )
+                self._log_result(step, timeout_result)
+                return timeout_result
+
+            # Don't sleep past the timeout
+            remaining = polling.max_timeout - elapsed
+            actual_wait = min(polling.interval, remaining)
+            if actual_wait <= 0:
+                continue
+            print(
+                f"  [polling] '{step.name}' attempt {attempt}: "
+                f"waiting {actual_wait:.0f}s before retry..."
+            )
+            self._interruptible_sleep(actual_wait)
+
+    @staticmethod
+    def _get_nested(data, key_path: str):
+        """Traverse a dict/list by dot-separated key path.
+
+        Supports array indexing via numeric segments, e.g.
+        ``"applications.0.status"`` resolves to ``data["applications"][0]["status"]``.
+        Negative indices are supported, e.g. ``"applications.-1.status"``
+        resolves to the last element.
+
+        Returns None if any segment is not found.
+        """
+        current = data
+        for key in key_path.split("."):
+            if isinstance(current, dict) and key in current:
+                current = current[key]
+            elif isinstance(current, list) and (key.isdigit() or (key.startswith("-") and key[1:].isdigit())):
+                idx = int(key)
+                if -len(current) <= idx < len(current):
+                    current = current[idx]
+                else:
+                    return None
+            else:
+                return None
+        return current
+
+    def _execute_once(self, step: StepDefinition, log_to_csv: bool = True) -> StepResult:
+        """Execute a single API step.
+
+        Phases:
+            1. Resolve ``${step.key}`` references in headers and payload.
+            2. Apply unique field generation if ``unique_fields`` is set.
+            3. Execute the HTTP request with a 30 s timeout.
+            4. Store dict responses in :class:`ResponseStore`.
+            5. Log the request/response as a :class:`LogEntry`.
+
+        Args:
+            step: The step definition to execute.
+
+        Returns:
+            A :class:`StepResult` capturing status code, body, timing, and errors.
+        """
+        # Phase 1: Resolve references in url, headers, and payload
+        resolved_url = self.resolver.resolve(step.url)
+        resolved_headers = self.resolver.resolve(step.headers)
+        resolved_payload = self.resolver.resolve(step.payload) if step.payload else None
+
+        # Phase 2: Generate unique fields if specified
+        if resolved_payload and step.unique_fields:
+            resolved_payload = self.generator.apply(resolved_payload, step.unique_fields)
+
+        # Phase 3: Execute HTTP request
+        start = time.monotonic()
+        opened_files: list = []
+        try:
+            # Build request kwargs based on whether this is a file upload
+            request_kwargs: dict = {
+                "method": step.method,
+                "url": resolved_url,
+                "headers": resolved_headers,
+                "timeout": 30,
+            }
+
+            opened_files = []
+            if step.files:
+                # Multipart file upload — open files and attach as multipart/form-data
+                files_dict = {}
+                for field_name, file_path in step.files.items():
+                    p = Path(file_path)
+                    mime_type = mimetypes.guess_type(p.name)[0] or "application/octet-stream"
+                    fh = open(p, "rb")
+                    opened_files.append(fh)
+                    files_dict[field_name] = (p.name, fh, mime_type)
+                request_kwargs["files"] = files_dict
+                # Send any extra payload fields as form data alongside the file
+                if resolved_payload:
+                    request_kwargs["data"] = resolved_payload
+            else:
+                request_kwargs["json"] = resolved_payload
+
+            response = requests.request(**request_kwargs)
+            duration_ms = (time.monotonic() - start) * 1000
+
+            try:
+                body = response.json()
+            except ValueError:
+                body = response.text
+
+            # Phase 4: Store response for downstream steps
+            if isinstance(body, dict):
+                self.store.save(step.name, body)
+
+            result = StepResult(
+                step_name=step.name,
+                status_code=response.status_code,
+                response_body=body,
+                duration_ms=duration_ms,
+                success=200 <= response.status_code < 300,
+            )
+
+        except requests.RequestException as e:
+            duration_ms = (time.monotonic() - start) * 1000
+            result = StepResult(
+                step_name=step.name,
+                status_code=-1,
+                response_body="",
+                duration_ms=duration_ms,
+                success=False,
+                error=str(e),
+            )
+        finally:
+            for fh in opened_files:
+                fh.close()
+
+        # Phase 5: Log regardless of outcome (unless suppressed for polling)
+        if log_to_csv:
+            self._log_result(step, result)
+
+        return result
+
+    def _log_result(self, step: StepDefinition, result: StepResult) -> None:
+        """Write a single result entry to the logger."""
+        resolved_url = self.resolver.resolve(step.url)
+        resolved_headers = self.resolver.resolve(step.headers)
+        resolved_payload = self.resolver.resolve(step.payload) if step.payload else None
+
+        self.logger.log(
+            LogEntry(
+                timestamp=datetime.now(IST).isoformat(),
+                step_name=result.step_name,
+                method=step.method,
+                url=resolved_url,
+                request_headers=json.dumps(resolved_headers),
+                request_body=json.dumps(resolved_payload) if resolved_payload else "",
+                status_code=result.status_code,
+                response_body=(
+                    json.dumps(result.response_body)
+                    if isinstance(result.response_body, dict)
+                    else str(result.response_body)
+                ),
+                duration_ms=result.duration_ms,
+                error=result.error,
+            )
+        )
+
+    def _interruptible_sleep(self, seconds: float) -> None:
+        """Sleep for the given duration, checking for pause every 0.5s."""
+        remaining = seconds
+        while remaining > 0:
+            if self.pause_controller:
+                self.pause_controller.wait_if_paused()
+            chunk = min(0.5, remaining)
+            time.sleep(chunk)
+            remaining -= chunk

api_chain_runner/generator.py

@@ -0,0 +1,126 @@
+"""Unique data generator for fields that must differ per run."""
+
+from __future__ import annotations
+
+import copy
+import random
+import string
+import time
+import uuid
+
+
+class UniqueDataGenerator:
+    """Generates unique values for email, PAN, and mobile fields.
+
+    Each call produces a distinct value with high probability via
+    timestamp/UUID suffixes (email) or random generation (PAN, mobile).
+    """
+
+    # Fourth character of a PAN encodes the entity type.
+    _PAN_FOURTH_CHARS = "PCHFAT"
+
+    def generate_email(self, base: str = "user") -> str:
+        """Generate a unique RFC-valid email address.
+
+        Uses a combination of timestamp and a short UUID fragment to
+        guarantee uniqueness across runs.
+
+        Args:
+            base: Local-part prefix (default ``"user"``).
+
+        Returns:
+            An email string like ``"user_1718901234_a1b2c3@test.com"``.
+        """
+        ts = int(time.time())
+        uid = uuid.uuid4().hex[:6]
+        return f"{base}_{ts}_{uid}@test.com"
+
+    def generate_pan(self) -> str:
+        """Generate a valid-format Indian PAN number.
+
+        Format: ``[A-Z]{3}[PCHFAT][A-Z][0-9]{4}[A-Z]``
+
+        The fourth character is one of P (individual), C (company),
+        H (HUF), F (firm), A (AOP), or T (trust).
+
+        Returns:
+            A 10-character PAN string.
+        """
+        first_three = "".join(random.choices(string.ascii_uppercase, k=3))
+        # Need to put when other type of cusomer are coming
+        # fourth = random.choice(self._PAN_FOURTH_CHARS) 
+        fourth = "P" # Our customer base is Indiviual
+        fifth = random.choice(string.ascii_uppercase)
+        digits = "".join(random.choices(string.digits, k=4))
+        last = random.choice(string.ascii_uppercase)
+        return f"{first_three}{fourth}{fifth}{digits}{last}"
+
+    def generate_mobile(self) -> str:
+        """Generate a 10-digit Indian mobile number.
+
+        Indian mobile numbers start with a digit in the range 6-9,
+        followed by 9 random digits.
+
+        Returns:
+            A 10-digit numeric string.
+        """
+        first = str(random.randint(6, 9))
+        rest = "".join(random.choices(string.digits, k=9))
+        return f"{first}{rest}"
+
+    def generate_udyam(self) -> str:
+        """Generate a valid-format UDYAM registration number.
+
+        Format: ``UDYAM-XX-99-9999999`` where X is an uppercase letter
+        and 9 is a random digit.
+
+        Returns:
+            A UDYAM string like ``"UDYAM-KA-23-1234567"``.
+        """
+        letters = string.ascii_uppercase
+        return (
+            "UDYAM-"
+            + random.choice(letters)
+            + random.choice(letters)
+            + "-"
+            + str(random.randint(10, 99))
+            + "-"
+            + str(random.randint(1000000, 9999999))
+        )
+
+    def apply(self, payload: dict, unique_fields: dict[str, str]) -> dict:
+        """Apply generated unique values to specified payload paths.
+
+        Creates a deep copy of *payload*, then for each entry in
+        *unique_fields* generates a value and sets it at the
+        dot-notation path.
+
+        Args:
+            payload: The original request body dict.
+            unique_fields: Mapping of ``"dotted.path"`` to generator
+                type (``"email"``, ``"pan"``, or ``"mobile"``).
+
+        Returns:
+            A new dict with unique values injected. The original
+            *payload* is never mutated.
+        """
+        result = copy.deepcopy(payload)
+
+        generators = {
+            "email": self.generate_email,
+            "pan": self.generate_pan,
+            "mobile": self.generate_mobile,
+            "udyam": self.generate_udyam,
+        }
+
+        for field_path, gen_type in unique_fields.items():
+            value = generators[gen_type]()
+            keys = field_path.split(".")
+            target = result
+
+            for key in keys[:-1]:
+                target = target[key]
+
+            target[keys[-1]] = value
+
+        return result

api_chain_runner/logger.py

@@ -0,0 +1,89 @@
+"""ResultLogger — logs every API call to CSV or Excel."""
+
+from __future__ import annotations
+
+import csv
+import dataclasses
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from api_chain_runner.models import LogEntry
+
+COLUMNS = [
+    "timestamp",
+    "step_name",
+    "method",
+    "url",
+    "request_headers",
+    "request_body",
+    "status_code",
+    "response_body",
+    "duration_ms",
+    "error",
+]
+
+
+class ResultLogger:
+    """Logs every API call to a CSV or Excel file.
+
+    Parameters
+    ----------
+    output_path:
+        Destination file path (e.g. ``"results.csv"``).
+    fmt:
+        Output format — ``"csv"`` or ``"xlsx"``.
+    """
+
+    def __init__(self, output_path: str, fmt: str = "csv") -> None:
+        if fmt not in ("csv", "xlsx"):
+            raise ValueError(f"Unsupported format '{fmt}'. Must be 'csv' or 'xlsx'.")
+        self._output_path = Path(output_path)
+        self._fmt = fmt
+        self._entries: list[LogEntry] = []
+
+    def log(self, entry: LogEntry) -> None:
+        """Append a log entry for a single API call."""
+        self._entries.append(entry)
+
+    def finalize(self) -> None:
+        """Flush all accumulated entries to the output file."""
+        if self._fmt == "csv":
+            self._write_csv()
+        else:
+            self._write_xlsx()
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _entry_to_row(self, entry: LogEntry) -> list[str]:
+        """Convert a LogEntry to a list of string values matching COLUMNS order."""
+        d = dataclasses.asdict(entry)
+        return [str(d[col]) if d[col] is not None else "" for col in COLUMNS]
+
+    def _write_csv(self) -> None:
+        self._output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self._output_path, "w", newline="", encoding="utf-8") as fh:
+            writer = csv.writer(fh)
+            writer.writerow(COLUMNS)
+            for entry in self._entries:
+                writer.writerow(self._entry_to_row(entry))
+
+    def _write_xlsx(self) -> None:
+        try:
+            from openpyxl import Workbook
+        except ImportError as exc:
+            raise ImportError(
+                "openpyxl is required for Excel output. Install it with: pip install openpyxl"
+            ) from exc
+
+        wb = Workbook()
+        ws = wb.active
+        ws.title = "API Results"
+        ws.append(COLUMNS)
+        for entry in self._entries:
+            ws.append(self._entry_to_row(entry))
+
+        self._output_path.parent.mkdir(parents=True, exist_ok=True)
+        wb.save(str(self._output_path))