api-chain-runner 1.0.0__tar.gz

api_chain_runner-1.0.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+.kiro/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# pytest
+.pytest_cache/
+
+# Environment variables
+.env
+
+# Results/output
+results.csv

api_chain_runner-1.0.0/ARCHITECTURE.md

@@ -0,0 +1,405 @@
+# API Chain Runner - Architecture & Design Patterns
+
+## 1. HIGH-LEVEL DESIGN (HLD)
+
+### What is HLD?
+HLD describes the **overall system structure** - how major components interact at a high level, without diving into implementation details. It answers: "What are the main parts and how do they talk to each other?"
+
+### System Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    CLI Entry Point                          │
+│                   (__main__.py)                             │
+│  - Parse arguments                                          │
+│  - Substitute environment variables                         │
+│  - Create ChainRunner                                       │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│              ChainRunner (Orchestrator)                      │
+│  - Loads YAML config                                        │
+│  - Initializes all components                               │
+│  - Executes steps sequentially                              │
+│  - Aggregates results                                       │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+        ┌────────────┼────────────┬──────────────┐
+        │            │            │              │
+        ▼            ▼            ▼              ▼
+    ┌────────┐  ┌────────┐  ┌──────────┐  ┌──────────┐
+    │ Store  │  │Resolver│  │Generator │  │ Executor │
+    │        │  │        │  │          │  │          │
+    │Saves & │  │Replaces│  │Generates │  │Makes HTTP│
+    │retrieves│  │${...}  │  │unique    │  │requests  │
+    │responses│  │with    │  │data      │  │          │
+    │        │  │values  │  │          │  │          │
+    └────────┘  └────────┘  └──────────┘  └──────────┘
+        │            │            │              │
+        └────────────┼────────────┴──────────────┘
+                     │
+                     ▼
+            ┌─────────────────┐
+            │  ResultLogger   │
+            │                 │
+            │ Logs all        │
+            │ requests/       │
+            │ responses to    │
+            │ CSV/XLSX        │
+            └─────────────────┘
+```
+
+### Key Components at HLD Level
+
+| Component | Purpose | Responsibility |
+|-----------|---------|-----------------|
+| **ChainRunner** | Orchestrator | Loads config, initializes components, runs steps |
+| **ResponseStore** | Data Cache | Stores API responses for cross-step sharing |
+| **ReferenceResolver** | Dynamic Substitution | Replaces `${step.key}` with actual values |
+| **UniqueDataGenerator** | Data Generation | Creates unique test data |
+| **StepExecutor** | Execution Engine | Makes HTTP requests, handles polling |
+| **ResultLogger** | Output Handler | Writes results to CSV/XLSX |
+
+### Data Flow at HLD Level
+
+```
+YAML Config
+    ↓
+ChainRunner.load_chain() → Parse & validate
+    ↓
+ChainRunner.run() → For each step:
+    ├─ ReferenceResolver.resolve() → Replace ${...}
+    ├─ UniqueDataGenerator.apply() → Inject unique data
+    ├─ StepExecutor.execute() → Make HTTP call
+    ├─ ResponseStore.save() → Store response
+    └─ ResultLogger.log() → Record details
+    ↓
+ResultLogger.finalize() → Write CSV/XLSX
+```
+
+---
+
+## 2. LOW-LEVEL DESIGN (LLD)
+
+### What is LLD?
+LLD describes **detailed implementation** - how each component works internally, what algorithms are used, data structures, and specific logic.
+
+### Component-Level Details
+
+#### **ChainRunner (runner.py)**
+```
+Responsibilities:
+  - Load YAML file and parse into StepDefinition objects
+  - Create and initialize all dependencies (Store, Resolver, Generator, Executor, Logger)
+  - Execute steps sequentially
+  - Handle errors based on continue_on_error flag
+  - Return ChainResult with all step results
+
+Key Methods:
+  __init__() → Initialize all components
+  load_chain() → Parse YAML, validate steps
+  _load_variables() → Pre-seed store with top-level variables
+  run() → Main execution loop
+```
+
+#### **StepExecutor (executor.py)**
+```
+Responsibilities:
+  - Execute a single API step
+  - Resolve references in URL, headers, payload
+  - Generate unique data for marked fields
+  - Make HTTP request with timeout (30 seconds)
+  - Handle polling (retry until expected value found)
+  - Store response in ResponseStore
+  - Catch and log errors
+
+Key Methods:
+  execute() → Main entry point, handles polling logic
+  _execute_once() → Single HTTP request execution
+  _get_nested() → Extract nested values from response
+```
+
+#### **ReferenceResolver (resolver.py)**
+```
+Responsibilities:
+  - Find all ${...} patterns in strings
+  - Parse reference format: ${step_name.key_path}
+  - Retrieve values from ResponseStore using dot-notation
+  - Recursively resolve nested structures (dicts, lists)
+  - Preserve data types for full-string references
+  - Raise clear errors for missing references
+
+Key Methods:
+  resolve() → Recursively resolve all references
+  find_references() → Extract ${...} patterns using regex
+  get_nested_value() → Traverse nested dicts with dot-notation
+```
+
+#### **ResponseStore (store.py)**
+```
+Responsibilities:
+  - Store API responses keyed by step name
+  - Retrieve values using dot-notation paths
+  - Support nested key access (e.g., "data.user.id")
+
+Key Methods:
+  save() → Store response under step name
+  get() → Retrieve value using dot-notation
+  has() → Check if step response exists
+
+Data Structure:
+  _data: dict[str, dict] = {
+    "auth": {"idToken": "abc123", "userId": 42},
+    "create_lead": {"leadId": "lead_001", "status": "PENDING"}
+  }
+```
+
+#### **UniqueDataGenerator (generator.py)**
+```
+Responsibilities:
+  - Generate unique emails (timestamp + UUID)
+  - Generate valid Indian PAN numbers
+  - Generate valid Indian mobile numbers
+  - Apply generators to specified payload fields
+
+Key Methods:
+  generate_email() → Create unique email
+  generate_pan() → Create valid PAN (format: [A-Z]{3}P[A-Z][0-9]{4}[A-Z])
+  generate_mobile() → Create valid mobile (10 digits, 6-9 start)
+  apply() → Inject generated values into payload
+```
+
+#### **ResultLogger (logger.py)**
+```
+Responsibilities:
+  - Log every API call with full details
+  - Support CSV and XLSX output formats
+  - Create output directories if needed
+  - Write headers and data rows
+
+Key Methods:
+  log() → Add a log entry
+  finalize() → Write all logs to file
+  _entry_to_row() → Convert LogEntry to CSV row
+```
+
+---
+
+## 3. DESIGN PATTERNS USED
+
+### Pattern 1: **Dependency Injection (DI)**
+
+**What it is:** Pass dependencies to a class instead of creating them inside.
+
+**Where it's used:**
+```python
+# In StepExecutor.__init__()
+def __init__(
+    self,
+    resolver: ReferenceResolver,      # Injected
+    generator: UniqueDataGenerator,   # Injected
+    store: ResponseStore,             # Injected
+    logger: ResultLogger,             # Injected
+) -> None:
+    self.resolver = resolver
+    self.generator = generator
+    self.store = store
+    self.logger = logger
+```
+
+**Why it's good:**
+- Easy to test (pass mock objects)
+- Loose coupling (components don't create each other)
+- Flexible (can swap implementations)
+
+---
+
+### Pattern 2: **Strategy Pattern**
+
+**What it is:** Different algorithms for the same task, selected at runtime.
+
+**Where it's used:**
+```python
+# In UniqueDataGenerator
+unique_fields = {
+    "email": "email",      # Strategy: generate email
+    "pan": "pan",          # Strategy: generate PAN
+    "mobile": "mobile"     # Strategy: generate mobile
+}
+
+# In ResultLogger
+fmt = "csv"   # Strategy: write CSV
+fmt = "xlsx"  # Strategy: write XLSX
+```
+
+**Why it's good:**
+- Easy to add new generator types
+- Easy to add new output formats
+- No if-else chains
+
+---
+
+### Pattern 3: **Template Method Pattern**
+
+**What it is:** Define skeleton of algorithm, let subclasses fill in details.
+
+**Where it's used:**
+```python
+# In StepExecutor.execute()
+def execute(self, step: StepDefinition) -> StepResult:
+    if not step.polling:
+        return self._execute_once(step)  # Simple case
+    
+    # Polling case: retry until condition met
+    while time.monotonic() - start_time < polling.max_timeout:
+        result = self._execute_once(step)  # Template method
+        if result.response_data.get(polling.key_path) in polling.expected_values:
+            return result
+        time.sleep(polling.interval)
+```
+
+**Why it's good:**
+- Reusable logic for both simple and polling cases
+- Clear separation of concerns
+
+---
+
+### Pattern 4: **Factory Pattern**
+
+**What it is:** Create objects without specifying exact classes.
+
+**Where it's used:**
+```python
+# In ChainRunner.__init__()
+self.store = ResponseStore()
+self.resolver = ReferenceResolver(self.store)
+self.generator = UniqueDataGenerator()
+self.logger = ResultLogger(output_path)
+self.executor = StepExecutor(
+    resolver=self.resolver,
+    generator=self.generator,
+    store=self.store,
+    logger=self.logger,
+)
+```
+
+**Why it's good:**
+- Centralized object creation
+- Easy to modify how objects are created
+- Single place to initialize dependencies
+
+---
+
+### Pattern 5: **Decorator Pattern (Implicit)**
+
+**What it is:** Add behavior to objects without modifying them.
+
+**Where it's used:**
+```python
+# In StepExecutor._execute_once()
+# Original payload is "decorated" with:
+# 1. Resolved references
+# 2. Generated unique data
+# 3. Logging wrapper
+
+resolved_payload = self.resolver.resolve(step.payload)
+unique_payload = self.generator.apply(resolved_payload, step.unique_fields)
+# Then logged
+```
+
+**Why it's good:**
+- Payload is enhanced step-by-step
+- Each enhancement is independent
+- Original payload not modified
+
+---
+
+### Pattern 6: **Chain of Responsibility (Implicit)**
+
+**What it is:** Pass request through chain of handlers.
+
+**Where it's used:**
+```python
+# In ChainRunner.run()
+for step in self.steps:
+    result = self.executor.execute(step)
+    # Each step's output becomes input for next step
+    # Via ResponseStore
+```
+
+**Why it's good:**
+- Steps are loosely coupled
+- Easy to add/remove steps
+- Each step doesn't know about others
+
+---
+
+## 4. CODING ARCHITECTURE SUMMARY
+
+### Layered Architecture
+
+```
+┌─────────────────────────────────────────┐
+│     Presentation Layer                  │
+│  (__main__.py - CLI Interface)          │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│     Orchestration Layer                 │
+│  (ChainRunner - Coordinates execution)  │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│     Business Logic Layer                │
+│  - StepExecutor (execution)             │
+│  - ReferenceResolver (substitution)     │
+│  - UniqueDataGenerator (data gen)       │
+│  - ResponseStore (data cache)           │
+└─────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────┐
+│     Data Layer                          │
+│  - ResultLogger (persistence)           │
+│  - Models (data contracts)              │
+└─────────────────────────────────────────┘
+```
+
+### Key Principles
+
+| Principle | Implementation |
+|-----------|-----------------|
+| **Single Responsibility** | Each class has one job (Executor executes, Resolver resolves, etc.) |
+| **Open/Closed** | Open for extension (add new generators), closed for modification |
+| **Dependency Inversion** | Depend on abstractions (interfaces), not concrete classes |
+| **DRY (Don't Repeat Yourself)** | Shared logic in ResponseStore, ReferenceResolver |
+| **Separation of Concerns** | HTTP logic separate from data generation, logging, etc. |
+
+---
+
+## 5. QUICK REFERENCE TABLE
+
+| Aspect | Details |
+|--------|---------|
+| **Architecture Type** | Layered + Component-based |
+| **Design Patterns** | DI, Strategy, Template Method, Factory, Decorator, Chain of Responsibility |
+| **Data Flow** | YAML → ChainRunner → StepExecutor → ResponseStore → ResultLogger |
+| **Error Handling** | Try-catch with continue_on_error flag |
+| **Extensibility** | Easy to add new generators, output formats, step types |
+| **Testability** | High (DI makes mocking easy) |
+| **Coupling** | Low (components communicate via interfaces) |
+| **Cohesion** | High (each component has clear responsibility) |
+
+---
+
+## 6. WHEN TO USE EACH PATTERN (For Your Future Projects)
+
+| Pattern | Use When |
+|---------|----------|
+| **Dependency Injection** | You want testable, loosely-coupled code |
+| **Strategy** | You have multiple algorithms for same task |
+| **Template Method** | You have similar algorithms with variations |
+| **Factory** | You need centralized object creation |
+| **Decorator** | You want to add behavior without modifying original |
+| **Chain of Responsibility** | You have sequential processing with loose coupling |
+

api_chain_runner-1.0.0/FROZENSET_EXPLANATION.md

@@ -0,0 +1,208 @@
+# Why frozenset Instead of tuple or list?
+
+## Quick Answer
+**frozenset** is used because:
+1. **Immutable** - Can't be accidentally modified
+2. **Fast lookups** - O(1) instead of O(n)
+3. **Semantic clarity** - Shows "this is a collection of valid values"
+4. **Prevents bugs** - Protects against accidental changes
+
+---
+
+## Detailed Comparison
+
+### 1. **Performance: Lookup Speed**
+
+#### Using List
+```python
+VALID_HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+
+# Checking if method is valid
+if method in VALID_HTTP_METHODS:  # O(n) - checks every item
+    pass
+```
+- **Time Complexity**: O(n) - has to check each item
+- For 7 items: checks up to 7 items
+- For 1000 items: checks up to 1000 items
+
+#### Using Tuple
+```python
+VALID_HTTP_METHODS = ("GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS")
+
+if method in VALID_HTTP_METHODS:  # O(n) - still checks every item
+    pass
+```
+- **Time Complexity**: O(n) - same as list
+- Slightly faster than list, but still slow for large collections
+
+#### Using frozenset
+```python
+VALID_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"})
+
+if method in VALID_HTTP_METHODS:  # O(1) - instant lookup
+    pass
+```
+- **Time Complexity**: O(1) - instant, uses hash table
+- Same speed whether 7 items or 7000 items
+
+### Real-World Impact
+```python
+# If you validate 1 million API calls:
+# List: 1,000,000 × 7 = 7,000,000 comparisons
+# frozenset: 1,000,000 × 1 = 1,000,000 comparisons (7x faster!)
+```
+
+---
+
+### 2. **Immutability: Preventing Bugs**
+
+#### Using List (DANGEROUS)
+```python
+VALID_HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+
+# Somewhere in code, someone accidentally modifies it:
+VALID_HTTP_METHODS.append("INVALID_METHOD")  # ❌ BUG! Now validation is broken
+VALID_HTTP_METHODS.pop()  # ❌ BUG! Removed a valid method
+
+# Now all validation is wrong for the entire application
+```
+
+#### Using Tuple (SAFER)
+```python
+VALID_HTTP_METHODS = ("GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS")
+
+VALID_HTTP_METHODS.append("INVALID_METHOD")  # ❌ Error: tuple has no append
+VALID_HTTP_METHODS[0] = "INVALID"  # ❌ Error: tuple doesn't support item assignment
+```
+- Prevents accidental modification
+- But you can still do: `VALID_HTTP_METHODS = ["GET"]` (reassign the variable)
+
+#### Using frozenset (SAFEST)
+```python
+VALID_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"})
+
+VALID_HTTP_METHODS.add("INVALID_METHOD")  # ❌ Error: frozenset has no add
+VALID_HTTP_METHODS.remove("GET")  # ❌ Error: frozenset has no remove
+VALID_HTTP_METHODS = ["GET"]  # ❌ Error: can't reassign (if using const)
+```
+- Completely immutable
+- No way to modify it
+- Protects the entire application
+
+---
+
+### 3. **Semantic Clarity: What Does It Mean?**
+
+#### Using List
+```python
+VALID_HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+# Unclear: Is order important? Can it be modified? Is it a queue?
+```
+
+#### Using Tuple
+```python
+VALID_HTTP_METHODS = ("GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS")
+# Clearer: Immutable, but order might matter
+```
+
+#### Using frozenset
+```python
+VALID_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"})
+# Crystal clear: This is a fixed collection of valid values
+# Order doesn't matter, can't be modified, fast lookups
+```
+
+---
+
+## Comparison Table
+
+| Feature | List | Tuple | frozenset |
+|---------|------|-------|-----------|
+| **Lookup Speed** | O(n) ❌ | O(n) ❌ | O(1) ✅ |
+| **Immutable** | No ❌ | Yes ✅ | Yes ✅ |
+| **Can be hashed** | No ❌ | Yes ✅ | Yes ✅ |
+| **Order matters** | Yes | Yes | No |
+| **Duplicates allowed** | Yes | Yes | No |
+| **Memory efficient** | Medium | Good | Good |
+| **Use for validation** | Bad | OK | Best ✅ |
+
+---
+
+## Real Code Example from Your Project
+
+```python
+# In models.py - StepDefinition.validate()
+def validate(self) -> None:
+    method_upper = self.method.upper() if self.method else ""
+    if method_upper not in VALID_HTTP_METHODS:  # ← This lookup happens for EVERY step
+        raise ConfigurationError(...)
+    
+    if self.unique_fields:
+        for field_path, gen_type in self.unique_fields.items():
+            if gen_type not in VALID_GENERATOR_TYPES:  # ← This lookup happens for EVERY field
+                raise ConfigurationError(...)
+```
+
+**Why frozenset matters here:**
+- If you have 100 steps with 5 fields each = 500 lookups
+- With list: 500 × 3 = 1500 comparisons
+- With frozenset: 500 × 1 = 500 comparisons (3x faster!)
+
+---
+
+## When to Use Each
+
+| Use Case | Best Choice |
+|----------|-------------|
+| **Fixed set of valid values** | frozenset ✅ |
+| **Ordered sequence** | tuple or list |
+| **Mutable collection** | list |
+| **Performance-critical lookups** | frozenset ✅ |
+| **Prevent accidental modification** | frozenset ✅ |
+| **Use as dictionary key** | frozenset ✅ (tuple also works) |
+
+---
+
+## What If You Used List Instead?
+
+```python
+# ❌ BAD - Using list
+VALID_HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+
+# In validate() method - called 1000 times per run
+if method_upper not in VALID_HTTP_METHODS:  # O(n) lookup, 1000 times
+    raise ConfigurationError(...)
+
+# Result: Slower validation, risk of accidental modification
+```
+
+```python
+# ✅ GOOD - Using frozenset
+VALID_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"})
+
+# In validate() method - called 1000 times per run
+if method_upper not in VALID_HTTP_METHODS:  # O(1) lookup, 1000 times
+    raise ConfigurationError(...)
+
+# Result: Fast validation, impossible to accidentally modify
+```
+
+---
+
+## Key Takeaway
+
+**frozenset is the professional choice for:**
+- ✅ Constants that shouldn't change
+- ✅ Validation collections
+- ✅ Performance-critical lookups
+- ✅ Preventing bugs from accidental modification
+
+**Use list when:**
+- You need to modify the collection
+- Order matters
+- You need duplicates
+
+**Use tuple when:**
+- You need immutability but order matters
+- You want to use it as a dictionary key
+

api_chain_runner-1.0.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: api-chain-runner
+Version: 1.0.0
+Summary: Execute chained API calls defined in YAML configuration files
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: requests
+Requires-Dist: pyyaml
+Requires-Dist: openpyxl
+Provides-Extra: test
+Requires-Dist: hypothesis; extra == "test"
+Requires-Dist: pytest; extra == "test"