EU-Utility/PACKAGING.md

# EU-Utility Packaging Guide

This document describes the complete packaging setup for EU-Utility, designed for professional Python distribution and PyPI publication.

## 📦 Package Structure

```
EU-Utility/
├── setup.py              # Traditional setuptools configuration
├── pyproject.toml        # Modern Python packaging (PEP 517/518)
├── MANIFEST.in           # Source distribution file inclusion rules
├── Makefile              # Development task automation
├── requirements.txt      # Production dependencies
├── requirements-dev.txt  # Development dependencies
├── LICENSE               # MIT License
└── .github/
    └── workflows/
        └── ci.yml        # GitHub Actions CI/CD pipeline
```

## 🚀 Installation Methods

### For End Users

```bash
# Install from PyPI (when published)
pip install eu-utility

# Install with all optional features
pip install "eu-utility[all]"

# Install with specific features
pip install "eu-utility[spotify]"
pip install "eu-utility[discord]"
```

### For Developers

```bash
# Clone the repository
git clone https://github.com/ImpulsiveFPS/EU-Utility.git
cd EU-Utility

# Install in development mode with all dev dependencies
pip install -e ".[dev]"

# Or use the Makefile
make install-dev
```

## 🛠️ Development Commands (Makefile)

### Installation
```bash
make install          # Install production dependencies
make install-dev      # Install development dependencies
make install-all      # Install all dependencies including optional features
```

### Testing
```bash
make test             # Run all tests
make test-unit        # Run unit tests only
make test-coverage    # Run tests with coverage report
make test-fast        # Run fast tests (excludes slow and UI tests)
```

### Code Quality
```bash
make lint             # Run all linters (flake8, mypy)
make format           # Format code with black and isort
make format-check     # Check code formatting without modifying files
```

### Security
```bash
make security         # Run all security checks
make security-bandit  # Run Bandit security analysis
make security-safety  # Run Safety vulnerability check
```

### Building and Distribution
```bash
make build            # Build source and wheel distributions
make build-check      # Check the built distributions
make upload-test      # Upload to TestPyPI
make upload-prod      # Upload to PyPI
```

### Cleanup
```bash
make clean            # Remove build artifacts and cache files
make clean-all        # Remove all generated files including virtual environments
```

## 🔧 Tool Configurations (pyproject.toml)

### Black (Code Formatter)
- Line length: 100 characters
- Target Python versions: 3.11, 3.12

### isort (Import Sorting)
- Profile: black (compatible with black formatting)
- Known first-party packages: core, plugins

### flake8 (Linter)
- Max line length: 100
- Max complexity: 10
- Extends ignore: E203, E501, W503 (black compatibility)

### mypy (Type Checker)
- Python version: 3.11
- Strict mode enabled
- Missing imports ignored for certain modules (PyQt6, OCR libraries)

### pytest (Testing)
- Test directory: tests/
- Coverage minimum: 80%
- Coverage reports: terminal, HTML, XML

### Bandit (Security)
- Excludes: tests, venv directories
- Skips: B101 (assert_used), B311 (random)

## 📋 CI/CD Pipeline (GitHub Actions)

The CI/CD pipeline runs on every push and pull request:

1. **Lint and Format Check**: Verifies code style with black, isort, flake8, and mypy
2. **Security Analysis**: Runs Bandit and Safety checks
3. **Tests**: Runs tests on multiple Python versions (3.11, 3.12) and OS (Ubuntu, Windows)
4. **Build**: Creates source and wheel distributions
5. **Test Installation**: Verifies the package can be installed
6. **Release**: Creates GitHub releases for tagged versions
7. **Publish**: Publishes to PyPI (only for tagged releases, not dev builds)

### Release Process

1. Update version in `core/__init__.py`
2. Update `CHANGELOG.md`
3. Commit and push changes
4. Create a git tag: `git tag v2.1.0`
5. Push the tag: `git push origin v2.1.0`
6. The CI pipeline will automatically:
   - Run all tests
   - Build the package
   - Create a GitHub release
   - Publish to PyPI

## 📦 Dependencies

### Production Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| PyQt6 | >=6.4.0 | GUI framework |
| keyboard | >=0.13.5 | Global hotkeys |
| psutil | >=5.9.0 | System monitoring |
| easyocr | >=1.7.0 | OCR (text recognition) |
| pytesseract | >=0.3.10 | Alternative OCR backend |
| pyautogui | >=0.9.54 | Screen capture |
| pillow | >=10.0.0 | Image processing |
| requests | >=2.28.0 | HTTP client |
| numpy | >=1.21.0 | Data processing |

### Development Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| pytest | >=7.4.0 | Testing framework |
| pytest-cov | >=4.1.0 | Coverage reporting |
| pytest-qt | >=4.2.0 | Qt testing |
| black | >=23.0.0 | Code formatting |
| flake8 | >=6.0.0 | Linting |
| mypy | >=1.5.0 | Type checking |
| bandit | >=1.7.5 | Security analysis |
| safety | >=2.3.0 | Vulnerability scanning |
| sphinx | >=7.0.0 | Documentation |
| build | >=0.10.0 | Package building |
| twine | >=4.0.0 | PyPI publishing |

## 🔒 Security Considerations

1. **Vulnerable files excluded**: Files ending with `_vulnerable.py`, `_insecure.py` are excluded from distribution
2. **Sensitive files excluded**: `.env`, `secrets.json`, `credentials.json` are never included
3. **Security scanning**: Bandit runs on every CI build
4. **Dependency scanning**: Safety checks for known vulnerabilities

## 📄 Entry Points

The package provides the following CLI commands after installation:

```bash
eu-utility          # Main application entry point
eu-utility-secure   # Secure/optimized version
eu-utility-gui      # GUI entry point (Windows)
```

## 🌐 Platform Support

- **Windows 10/11**: Full support with all features
- **Linux**: Core features supported (some Windows-specific features disabled)
- **macOS**: Not officially supported (contributions welcome)

## 📝 Publishing Checklist

Before publishing a new release:

- [ ] Version bumped in `core/__init__.py`
- [ ] `CHANGELOG.md` updated with release notes
- [ ] All tests passing locally (`make test`)
- [ ] Code formatted (`make format`)
- [ ] Linting passes (`make lint`)
- [ ] Security checks pass (`make security`)
- [ ] Build succeeds (`make build`)
- [ ] Package installs correctly (`make test-install`)
- [ ] Git tag created and pushed
- [ ] GitHub release notes prepared

## 🔗 Resources

- [Python Packaging User Guide](https://packaging.python.org/)
- [setuptools documentation](https://setuptools.pypa.io/)
- [pyproject.toml specification](https://packaging.python.org/en/latest/specifications/declaring-project-metadata/)
- [GitHub Actions documentation](https://docs.github.com/en/actions)
- [PyPI publishing guide](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/)