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:

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

# 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

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

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

# 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:

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."""

    @pytest.fixture
    def instance(self):
        """Create instance for testing."""
        return NewFeatureClass("test", 5)

    def test_initialization(self, instance):
        """Test class initialization."""
        assert instance.attribute1 == "test"
        assert instance.attribute2 == 5

    def test_method1(self, instance):
        """Test method1."""
        result = instance.method1()
        assert result == "test_5"

    def test_method2(self, instance):
        """Test method2."""
        result = instance.method2(3)
        assert result == 15

Generate integration tests if needed:

def test_integration_with_existing_code():
    """Test that new feature integrates with existing code."""
    # Setup
    data = prepare_test_data()

    # Execute workflow using new feature
    result = existing_workflow(data, use_new_feature=True)

    # Verify
    assert result["status"] == "success"
    assert "new_feature_output" in result

See [testing-strategies.md](references/testing-strategies.md) for comprehensive testing patterns.

6. Run Tests

Execute test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=module --cov-report=term-missing

# Run specific test file
pytest tests/test_new_feature.py

# Run with verbose output
pytest -v

Check results:

• All tests should pass
• Coverage should be adequate (>80% for new code)
• No regressions in existing tests

7. Fix Failing Tests

If tests fail, diagnose and fix:

Common issues:

1. Assertion failures

• Check expected vs actual values
• Verify test logic
• Fix implementation or test

2. Import errors

• Verify module paths
• Check __init__.py exports
• Ensure dependencies installed

3. Type errors

• Check function signatures
• Verify parameter types
• Update type hints if needed

4. Logic errors

• Debug implementation
• Add print statements
• Use pytest debugger: pytest --pdb

Example fix:

# Failing test
de