# Python Development Guidelines

## Project Structure

- Maintain clear directory structure:
  - src/ - Source code
  - tests/ - Test files
  - docs/ - Documentation
  - config/ - Configuration files

## Development Methodology

- Follow Test-Driven Development (TDD) principles:
  - Write tests first before implementation
  - Red-Green-Refactor cycle
  - Keep tests focused and meaningful
  - **Always update tests before modifying implementation**
  - **Run tests after implementation changes to verify**
- Embrace refactoring when needed:
  - Improve code structure without changing behavior
  - Use automated tests to verify refactoring
  - Follow SOLID principles during refactoring

## Code Quality

- Use type annotations for all functions and classes
- Add descriptive docstrings following PEP 257
- Maintain modular design with separate files for:
  - Models
  - Services
  - Controllers
  - Utilities
- Use environment variables for configuration
- Implement robust error handling and logging
- Follow code style with Ruff
- Use appropriate libraries when necessary
- **Ensure all linting checks pass after changes**
- **Run full test suite after modifications**

## Testing

- Use pytest and pytest plugins only (no unittest)
- Place all tests in ./tests directory
- Add **init**.py to new directories
- Include type annotations and docstrings in tests
- Import test fixtures when TYPE_CHECKING:

  ```python
  from _pytest.capture import CaptureFixture
  from _pytest.fixtures import FixtureRequest
  from _pytest.logging import LogCaptureFixture
  from _pytest.monkeypatch import MonkeyPatch
  from pytest_mock.plugin import MockerFixture
  ```

## Dependencies

- Use uv (<https://github.com/astral-sh/uv>) for dependency management
- Maintain virtual environments

## CI/CD

- Implement with GitHub Actions or GitLab CI
- **Verify all CI checks pass after each commit**

## Documentation

- Add comprehensive docstrings
- Maintain detailed README files
- Preserve existing comments
- Update related comments when modifying code
