6.9 KiB

Raw Blame History

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

# 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

# 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

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

Testing

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

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

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

Building and Distribution

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

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:

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

Release Process

Update version in core/__init__.py
Update CHANGELOG.md
Commit and push changes
Create a git tag: git tag v2.1.0
Push the tag: git push origin v2.1.0
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

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

📄 Entry Points

The package provides the following CLI commands after installation:

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

6.9 KiB Raw Blame History