For Developers

For Developers

For contributors, translators, and anyone who wants to run or build the project from source.

---

Prerequisites

Tool	Version	Purpose
Python	3.10 or 3.13 recommended	Runtime
pip	Latest	Package manager
Git	Any recent	Cloning the repo
PyInstaller	6.x	Building the .exe

Python 3.13 is what the project is currently compiled against. Avoid very recent versions, not all libraries may support them yet.

---

Clone & Install

git clone https://github.com/Hyacinthe-primus/File_Converter_Pro.git
cd File_Converter_Pro
pip install -r requirements.txt
pip install -r requirements-dev.txt             # Dev/Build dependencies
python main.py

---

Key Python Dependencies

Installed automatically via requirements.txt:

Package	Role
PySide6	UI framework (Qt6 bindings)
pdf2docx	PDF → DOCX layout-preserving pipeline
pymupdf (fitz)	PDF rendering and HTML export
reportlab	Native PDF generation fallback
pypandoc	Pandoc bridge (TXT/RTF/EPUB → PDF/DOCX)
python-docx	DOCX creation and editing
python-pptx	PPTX reading and rendering
openpyxl	XLSX reading and conversion
Pillow	Image conversion engine
pillow-heif	HEIC format support
striprtf	RTF text extraction fallback
matplotlib	Statistics dashboard charts
cryptography	Fernet-encrypted config storage
comtypes	Windows COM automation (Office/PowerPoint/Excel)

comtypes is Windows-only. It gracefully no-ops on machines without Office installed.

---

Optional External Binaries

Auto-detected at runtime. No path configuration needed.

Binary	Used for	Install
ffmpeg	All audio and video conversions	Bundled in the compiled exe. For dev: ffmpeg.org or winget install ffmpeg
pandoc	High-quality TXT/RTF/EPUB → PDF/DOCX	Download
MiKTeX / pdflatex	LaTeX-based PDF rendering via Pandoc	Download
wkhtmltopdf	HTML → PDF (pdfkit Strategy 1)	Download
soffice (LibreOffice)	PPTX/XLSX → PDF fallback	Download

---

Running in Dev Mode

python main.py --help

This prints all available flags (language, theme, context menu, achievement commands, etc.).

CLI output is only visible when running from source. The compiled .exe does not expose a console window.

---

Tests

# Run all tests
python -m pytest tests/ -v

# Run a specific test file
python -m pytest tests/test_mixins.py -v

# Run a specific test
python -m pytest tests/test_mixins.py::test_format_size_kb -v

# Run tests in fast mode (no verbose)
python -m pytest tests/ -q

# Run tests with error display
python -m pytest tests/ --tb=short

---

Ruff (Python Linter)

# Install ruff
pip install ruff

# Check all Python files
ruff check

# Check unused imports (F401)
ruff check --select F401

# Check unused variables (F841)
ruff check --select F841

# Check unused imports + variables
ruff check --select F401,F841

# Auto-fix unused imports
ruff check --select F401 --fix

# Auto-fix unused variables
ruff check --select F841 --fix --unsafe-fixes

# Auto-fix everything
ruff check --fix

# Code formatting (like black)
ruff format

# Check function complexity (C901)
ruff check --select C901

# Check duplicate imports (I001)
ruff check --select I001

---

Manual Checks

# Python syntax (check a file)
python -m py_compile file.py

# Run the application
python main.py

# Check file size
python -c "print(len(open('file.py').readlines()))"

---

Building the Exe

The project uses PyInstaller + UPX for compression. Build scripts are PowerShell-based.

1. Install build tools

pip install pyinstaller
winget install UPX.UPX

2. Build the main application

.\build.ps1

Runs PyInstaller with build.spec and produces dist/File Converter Pro/ (onedir output).

3. Build the Quick Check utility

.\build_quick_check.ps1

4. Package into an installer

.\build_installer.ps1

Calls Inno Setup with setup.iss and produces Output/FileConverterPro_Setup_<version>.exe.

Make sure Inno Setup is installed and on your PATH. Download: jrsoftware.org/isinfo.php

Full pipeline at once

Note: The Quick Check utility is not included in this pipeline and must be built separately using build_quick_check.ps1.

.\build_all.ps1

---

Project Structure

See the Directory Tree

Main window inheritance chain:

Inheritance chain (MRO):
      AppLogicMixin(OptimizationMixin, ImageToPdfMixin, BatchMixin, ...)
      └── AppUIMixin(FileManagementMixin, PanelsMixin, ..., AppLogicMixin)
            └── FileConverterApp(AppUIMixin, QMainWindow)  ← QMainWindow mixed in here
                  └── FadingMainWindow