incremental-python-programmer

# Incremental Python Programmer

Implement new features in Python repositories with automated testing and validation.

## Workflow

### 1. Understand the Feature Request

**Parse the request:**
- Identify what functionality is being requested
- Determine scope (function, class, module, or modification)
- Understand expected behavior and inputs/outputs
- Note any specific requirements or constraints

**Clarify if needed:**
- Ask about edge cases
- Confirm integration points
- Verify expected behavior
- Check for dependencies

### 2. Analyze Repository Structure

**Automated analysis:**
```bash
python scripts/analyze_repo_structure.py <repo_path>
```

**Manual analysis:**
- Identify relevant modules and files
- Understand existing code organization
- Find similar existing implementations
- Locate test directory structure
- Check coding conventions and patterns

**Key questions:**
- Where should the new code be placed?
- What existing code needs modification?
- What dependencies are needed?
- What patterns should be followed?

See [implementation-patterns.md](references/implementation-patterns.md) for common patterns.

### 3. Plan Implementation

**Determine implementation approach:**

**For new functions:**
- Identify appropriate module
- Determine function signature
- Plan implementation logic
- Identify dependencies

**For new classes:**
- Identify appropriate module or create new one
- Design class structure and methods
- Plan initialization and attributes
- Consider inheritance if applicable

**For new modules:**
- Determine module name and location
- Plan module structure
- Identify exports and public API
- Plan integration with existing code

**For modifications:**
- Identify code to modify
- Plan backward compatibility
- Determine parameter additions
- Plan integration with existing logic

### 4. Implement the Feature

Follow this order:

**Step 1: Add necessary imports**
```python
# Standard library
import os
from typing import List, Dict, Optional

# Third-party (add to requirements.txt if new)
import requests

# Local imports
from .existing_module import helper_function
```

**Step 2: Implement core functionality**
- Follow existing code style and conventions
- Use type hints consistently
- Add docstrings for all public functions/classes
- Include error handling
- Follow patterns from similar code

**Step 3: Integrate with existing code**
- Update relevant functions/classes
- Add new module to `__init__.py` if needed
- Update configuration if required
- Ensure backward compatibility

**Example: Adding a new function**
```python
def new_feature_function(param1: str, param2: int = 10) -> dict:
    """
    Brief description of what the function does.

    Args:
        param1: Description of param1
        param2: Description of param2 (default: 10)

    Returns:
        Dictionary containing results

    Raises:
        ValueError: If param1 is empty
        TypeError: If param2 is not an integer
    """
    # Validate inputs
    if not param1:
        raise ValueError("param1 cannot be empty")

    # Implementation
    result = {
        "input": param1,
        "multiplier": param2,
        "output": len(param1) * param2
    }

    return result
```

**Example: Adding a new class**
```python
class NewFeatureClass:
    """
    Class for handling new feature functionality.

    Attributes:
        attribute1: Description of attribute1
        attribute2: Description of attribute2
    """

    def __init__(self, param1: str, param2: int = 10):
        """
        Initialize NewFeatureClass.

        Args:
            param1: Description
            param2: Description (default: 10)
        """
        self.attribute1 = param1
        self.attribute2 = param2

    def method1(self) -> str:
        """Method description."""
        return f"{self.attribute1}_{self.attribute2}"

    def method2(self, value: int) -> int:
        """Method description."""
        return value * self.attribute2
```

**Example: Modifying existing code**
```python
# Before
def existing_function(param: str) -> str:
    return param.upper()

# After - adding new parameter with default
def existing_function(param: str, enable_new_feature: bool = False) -> str:
    result = param.upper()
    if enable_new_feature:
        result = apply_new_transformation(result)
    return result

def apply_new_transformation(text: str) -> str:
    """New feature logic."""
    return f"[TRANSFORMED] {text}"
```

See [implementation-patterns.md](references/implementation-patterns.md) for detailed patterns.

### 5. Generate Tests

**Identify test requirements:**
- What needs to be tested?
- What are the edge cases?
- What are the integration points?
- What error conditions exist?

**Generate unit tests:**

```python
import pytest
from module import new_feature_function, NewFeatureClass

class TestNewFeatureFunction:
    """Test suite for new_feature_function."""

    def test_basic_functionality(self):
        """Test basic functionality."""
        result = new_feature_function("test", 5)
        assert result["input"] == "test"
        assert result["multiplier"] == 5
        assert result["output"] == 20

    def test_default_parameter(self):
        """Test with default parameter."""
        result = new_feature_function("hello")
        assert result["multiplier"] == 10
        assert result["output"] == 50

    def test_empty_string_raises_error(self):
        """Test that empty string raises ValueError."""
        with pytest.raises(ValueError, match="cannot be empty"):
            new_feature_function("", 5)

    @pytest.mark.parametrize("input_str,multiplier,expected", [
        ("a", 1, 1),
        ("ab", 2, 4),
        ("abc", 3, 9),
    ])
    def test_various_inputs(self, input_str, multiplier, expected):
        """Test with various inputs."""
        result = new_feature_function(input_str, multiplier)
        assert result["output"] == expected


class TestNewFeatureClass:
    """Test suite for NewFeatureClass."