Oleksandr Kozachuk
fbec05dfe9
- Fix infinite retry loop in ai_responder.py that caused test_fix1 to hang - Add missing picture_edit parameter to all AIResponse constructor calls - Set up complete development toolchain with Black, isort, Bandit, and MyPy - Create comprehensive Makefile for development workflows - Add pre-commit hooks with formatting, linting, security, and type checking - Update test mocking to provide contextual responses for different scenarios - Configure all tools for 140 character line length and strict type checking - Add DEVELOPMENT.md with setup instructions and workflow documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
157 lines
4.1 KiB
Markdown
157 lines
4.1 KiB
Markdown
# Fjerkroa Bot Development Guide
|
|
|
|
This document outlines the development setup and workflows for the Fjerkroa Bot project.
|
|
|
|
## Development Tools Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.11 (required - use `python3.11` and `pip3.11` explicitly)
|
|
- Git
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# Install development dependencies
|
|
make install-dev
|
|
|
|
# Or manually:
|
|
pip3.11 install -r requirements.txt
|
|
pip3.11 install -e .
|
|
pre-commit install
|
|
```
|
|
|
|
## Available Development Commands
|
|
|
|
Use the Makefile for all development tasks. Run `make help` to see all available commands:
|
|
|
|
### Installation
|
|
- `make install` - Install production dependencies
|
|
- `make install-dev` - Install development dependencies and pre-commit hooks
|
|
|
|
### Code Quality
|
|
- `make lint` - Run linter (flake8)
|
|
- `make format` - Format code with black and isort
|
|
- `make format-check` - Check if code is properly formatted
|
|
- `make type-check` - Run type checker (mypy)
|
|
- `make security-check` - Run security scanner (bandit)
|
|
|
|
### Testing
|
|
- `make test` - Run tests
|
|
- `make test-fast` - Run tests without slow tests
|
|
- `make test-cov` - Run tests with coverage report
|
|
|
|
### Combined Operations
|
|
- `make all-checks` - Run all code quality checks and tests
|
|
- `make pre-commit` - Run all pre-commit checks (format, then check)
|
|
- `make ci` - Full CI pipeline (install deps and run all checks)
|
|
|
|
### Utility
|
|
- `make clean` - Clean up temporary files and caches
|
|
- `make run` - Run the bot (requires config.toml)
|
|
- `make run-dev` - Run the bot in development mode with auto-reload
|
|
|
|
## Tool Configuration
|
|
|
|
All development tools are configured via `pyproject.toml` and `.flake8`:
|
|
|
|
### Code Formatting (Black + isort)
|
|
- Line length: 140 characters
|
|
- Target Python version: 3.8+
|
|
- Imports sorted and formatted consistently
|
|
|
|
### Linting (Flake8)
|
|
- Max line length: 140
|
|
- Max complexity: 10
|
|
- Ignores: E203, E266, E501, W503, E306 (for Black compatibility)
|
|
|
|
### Type Checking (MyPy)
|
|
- Strict type checking enabled
|
|
- Checks both `fjerkroa_bot` and `tests` directories
|
|
- Ignores missing imports for external libraries
|
|
|
|
### Security Scanning (Bandit)
|
|
- Scans for security issues
|
|
- Skips known safe patterns (pickle, random) for this application
|
|
|
|
### Testing (Pytest)
|
|
- Configured for async tests
|
|
- Coverage reporting available
|
|
- Markers for slow tests
|
|
|
|
## Pre-commit Hooks
|
|
|
|
Pre-commit hooks are automatically installed with `make install-dev`. They run:
|
|
|
|
1. Built-in checks (trailing whitespace, file endings, etc.)
|
|
2. Black code formatter
|
|
3. isort import sorter
|
|
4. Flake8 linter
|
|
5. Bandit security scanner
|
|
6. MyPy type checker
|
|
7. Fast tests
|
|
|
|
To run pre-commit manually:
|
|
```bash
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
1. **Setup**: Run `make install-dev`
|
|
2. **Development**: Make your changes
|
|
3. **Check**: Run `make pre-commit` to format and check code
|
|
4. **Test**: Run `make test` or `make test-cov` for coverage
|
|
5. **Commit**: Git will automatically run pre-commit hooks
|
|
|
|
## Continuous Integration
|
|
|
|
The `make ci` command runs the complete CI pipeline:
|
|
- Installs all dependencies
|
|
- Runs linting (flake8)
|
|
- Checks formatting (black, isort)
|
|
- Runs type checking (mypy)
|
|
- Runs security scanning (bandit)
|
|
- Runs all tests
|
|
|
|
## File Structure
|
|
|
|
```
|
|
fjerkroa_bot/
|
|
├── fjerkroa_bot/ # Main package
|
|
├── tests/ # Test files
|
|
├── requirements.txt # Production dependencies
|
|
├── pyproject.toml # Tool configuration
|
|
├── .flake8 # Flake8 configuration
|
|
├── .pre-commit-config.yaml # Pre-commit configuration
|
|
├── Makefile # Development commands
|
|
└── setup.py # Package setup
|
|
```
|
|
|
|
## Adding Dependencies
|
|
|
|
1. Add to `requirements.txt` for production dependencies
|
|
2. Add to `pyproject.toml` for development dependencies
|
|
3. Run `make install-dev` to install
|
|
|
|
## Troubleshooting
|
|
|
|
### Pre-commit Issues
|
|
```bash
|
|
# Reset pre-commit
|
|
pre-commit clean
|
|
pre-commit install
|
|
```
|
|
|
|
### Tool Not Found Errors
|
|
Ensure you're using `python3.11` and `pip3.11` explicitly, and that all dependencies are installed:
|
|
```bash
|
|
make install-dev
|
|
```
|
|
|
|
### Type Check Errors
|
|
Install missing type stubs:
|
|
```bash
|
|
pip3.11 install types-requests types-toml
|
|
```
|