Python3 Add Feature

$ARGUMENTS

Python Feature Addition Workflow

The model guides feature development through discovery, planning, implementation, and verification phases.

Arguments

Instructions

1. Understand the feature request from arguments
2. Discover project context (structure, patterns, existing code)
3. Plan implementation (files to create/modify, dependencies)
4. Implement with tests following TDD
5. Verify quality (linting, types, coverage)

Phase 1: Discovery

Gather Project Context

CHECK:
- [ ] pyproject.toml exists and has project configuration
- [ ] src/ or packages/ directory structure
- [ ] tests/ directory with existing test patterns
- [ ] Linting and type-check configuration (ruff; ty and/or mypy per project — see python3-standards)
- [ ] Existing patterns for similar features

Identify Integration Points

Determine where the feature fits:

• Which module/package owns this functionality?
• What existing classes/functions will interact with it?
• What new files need to be created?

Phase 2: Planning

Feature Specification

Create a clear specification:

## Feature: [Name]

**Purpose**: [One sentence describing what this enables]

**User Story**: As a [user type], I want [capability] so that [benefit].

**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

**Files to Create/Modify**:
- `src/module/new_feature.py` - Main implementation
- `tests/test_new_feature.py` - Test suite
- `src/module/__init__.py` - Export new functionality

**Dependencies**:
- Internal: [existing modules to import]
- External: [new packages if any]

MoSCoW Prioritization

Categorize all requirements using MoSCoW:

Discipline Check: If everything is P0, nothing is P0. Re-evaluate.

Example:

### Requirements by Priority

**P0 (Must Have)**:
- [ ] Parse CSV input with header detection
- [ ] Output formatted report to stdout
- [ ] Handle malformed rows with error message

**P1 (Should Have)**:
- [ ] Support custom delimiter (--delimiter)
- [ ] Progress indicator for large files

**P2 (Could Have)**:
- [ ] JSON output format option
- [ ] Column filtering

**Won't Have (This Release)**:
- Excel format support (separate feature)
- Database export (requires new dependency)

Acceptance Criteria Formats

Use ONE of these formats for testable acceptance criteria:

Format 1: Given/When/Then (BDD)

Given [precondition]
When [user action]
Then [expected outcome]

Example:

Given a CSV file with 1000 rows
When the user runs `parse report.csv`
Then the output shows all rows within 2 seconds
And no memory warnings are logged

Format 2: Checklist with Specifics

- [ ] Command `parse --help` shows usage with examples
- [ ] Empty file input returns exit code 1 with message "Empty file"
- [ ] Unicode characters in data are preserved in output
- [ ] Ctrl+C during processing exits cleanly (no stack trace)

Anti-Patterns to Avoid:

Design Interface First

Define the public API before implementation:

# Define function signatures and docstrings
def new_feature(input_data: InputType, *, option: str = "default") -> ResultType:
    """Process input data with new feature capability.

    Args:
        input_data: The data to process
        option: Configuration option

    Returns:
        Processed result

    Raises:
        ValidationError: If input_data is invalid
    """
    ...

Phase 3: Test-Driven Implementation

Write Tests First

import pytest
from pytest_mock import MockerFixture


class TestNewFeature:
    """Tests for new_feature functionality."""

    def test_basic_operation(self) -> None:
        """Test basic feature operation with valid input."""
        # Arrange
        input_data = create_valid_input()

        # Act
        result = new_feature(input_data)

        # Assert
        assert result.status == "success"

    def test_handles_invalid_input(self) -> None:
        """Test feature raises error for invalid input."""
        with pytest.raises(ValidationError, match="Invalid input"):
            new_feature(invalid_input)

    def test_option_affects_behavior(self) -> None:
        """Test that option parameter changes processing."""
        result_default = new_feature(data, option="default")
        result_custom = new_feature(data, option="custom")

        assert result_default != result_custom

Implement to Pass Tests

1. Run tests - they should fail (red)
2. Implement minimal code to pass (green)
3. Refactor for quality (refactor)
4. Repeat for each test case

Implementation Checklist

- [ ] All functions have complete type hints
- [ ] Docstrings follow Google style
- [ ] Error handling uses specific exceptions
- [ ] No hardcoded values (use constants or config)
- [ ] Follows existing project patterns

Phase 4: Integration

Update Module Exports

# src/module/__init__.py
from .new_feature import new_feature, ResultType

__all__ = [
    "new_feature",
    "ResultType",
    # ... existing exports
]

Add to CLI (if applicable)

@app.command()
def feature_command(input_file: Annotated[Path, typer.Argument(help="Input file")]) -> None:
    """Run new feature on input file."""
    result = new_feature(load_data(input_file))
    console.print(f"Result: {result}")

Phase 5: Verification

Run Quality Checks

# Linting
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type checking — match hooks/CI (ty vs mypy); do not use mypy only because [tool.mypy] exists
uv run ty check src/ tests/
# If hooks/CI run mypy:
# uv run mypy src/ tests/

# Tests with coverage
uv run pytest tests/ --cov=src --cov-report=term-missing

Coverage Requirements

• New feature code: 100% coverage
• Integration points: Covered by integration tests
• Overall project: Maintain or improve existing coverage

Success Metrics

Define measurable success criteria before implementation:

Leading Indicators (Observable in days-weeks):

Lagging Indicators (Observable in weeks-months):

For CLI Features:

# Performance baseline
hyperfine 'uv run <command> <args>' --warmup 3

# Memory usage
/usr/bin/time -v uv run <command> <args> 2>&1 | grep "Maximum resident"

Evaluation Window: Specify when metrics will be reviewed (e.g., "1 week post-merge", "after 100 invocations").

Documentation

Update relevant documentation:

• README.md if user-facing feature
• API docs if public interface
• CHANGELOG.md with feature description

Example Workflow

Request: "Add CSV export functionality to the report module"

Discovery

Project structure:
- src/reports/generator.py - existing report generation
- src/reports/formats/ - existing format handlers
- tests/reports/ - existing report tests

Pattern: Format handlers inherit from BaseFormatter

Planning

## Feature: CSV Export

**Purpose**: Export reports in CSV format

**Files**:
- `src/reports/formats/csv_formatter.py` - CSV implementation
- `tests/reports/formats/test_csv_formatter.py` - Tests

**Interface**:
class CsvFormatter(BaseFormatter):
    def format(self, report: Report) -> str: ...

Implementation

1. Write tests for CsvFormatter
2. Implement CsvFormatter class
3. Register in format factory
4. Add CLI option --format csv
5. Run verification checks

Quality Standards

Consult ../python3-development/references/python3-standards.md when verifying the feature against shared plugin standards. Ensure:

1. Type Safety: All code passes the project's type checker — match hooks/CI (ty vs mypy); use uv run ty check when ty is what the repo runs; use uv run mypy only when mypy is actually invoked there (not merely because [tool.mypy] exists)
2. Linting: Zero ruff errors or warnings
3. Tests: New code has 100% coverage
4. Patterns: Follows existing project conventions
5. Documentation: Docstrings on all public interfaces

References

• pytest Documentation
• pytest-mock
• Google Python Style Guide