lego-instructions-manager/PYTHON_314_COMPATIBILITY.md

Python 3.14 Compatibility Guide for LEGO Instructions Manager

What Changed

All dependencies have been updated to ensure full Python 3.14 compatibility. Here's what was fixed:

Critical Updates (Had build errors):

1. Pillow 10.4.0 → >=11.0.0

   • Old version: No Python 3.14 prebuilt wheels, tried to compile from source
   • Fix: Pillow 11.0.0+ has prebuilt wheels for Python 3.14

2. PyMuPDF 1.23.8 → >=1.24.0

   • Old version: No Python 3.14 prebuilt wheels, compilation failed
   • Fix: PyMuPDF 1.24.0+ has prebuilt wheels for Python 3.14

3. SQLAlchemy 2.0.23 → >=2.0.35

   • Old version: Has TypingOnly assertion errors with Python 3.14
   • Fix: SQLAlchemy 2.0.35+ includes Python 3.14 compatibility fixes

Additional Improvements:

4. email-validator 2.1.0 → >=2.1.1

   • Old version: Was yanked from PyPI due to incorrect Python version metadata
   • Fix: Use 2.1.1 or higher

5. gunicorn → waitress

   • Issue: Gunicorn doesn't work on Windows (Unix-only)
   • Fix: Replaced with waitress, a proper Windows-compatible WSGI server

Version Flexibility:

All packages now use flexible version ranges (e.g., >=3.0.0,<4.0.0) instead of exact pins. This allows:

• Automatic minor/patch updates for bug fixes and security patches
• Better compatibility with Python updates
• Easier maintenance

Key Benefits

✅ No more compilation errors - All packages have prebuilt wheels for Python 3.14 ✅ Windows compatible - Uses waitress instead of gunicorn ✅ Security updates - Flexible versioning allows patch updates ✅ Future proof - Won't break with Python 3.14.x minor updates

Installation

Simply replace your E:\LIM\requirements.txt with the updated file and run:

start_lim.bat

The script will automatically:

1. Create/update the virtual environment
2. Install all compatible dependencies
3. Initialize the database
4. Start the application

If You Still Have Issues

If you encounter any problems:

1. Delete the virtual environment:

   rmdir /s E:\LIM\venv
   

2. Run start_lim.bat again - It will create a fresh environment

3. Check Python version:

   python --version
   

   Should show Python 3.14.x

Package Compatibility Matrix

Package	Old Version	New Version	Python 3.14 Support
Flask	3.0.0	>=3.0.0	✅ Yes
Werkzeug	3.0.1	>=3.0.0	✅ Yes
Flask-SQLAlchemy	3.1.1	>=3.1.1	✅ Yes
SQLAlchemy	2.0.23	>=2.0.35	✅ FIXED
Flask-Login	0.6.3	>=0.6.3	✅ Yes
Flask-Bcrypt	1.0.1	>=1.0.1	✅ Yes
Flask-WTF	1.2.1	>=1.2.1	✅ Yes
WTForms	3.1.1	>=3.1.1	✅ Yes
email-validator	2.1.0 (yanked)	>=2.1.1	✅ Yes
requests	2.31.0	>=2.31.0	✅ Yes
httpx	0.25.2	>=0.25.2	✅ Yes
Pillow	10.4.0	>=11.0.0	✅ FIXED
PyPDF2	3.0.1	>=3.0.1	✅ Yes
PyMuPDF	1.23.8	>=1.24.0	✅ FIXED
python-dotenv	1.0.0	>=1.0.0	✅ Yes
python-dateutil	2.8.2	>=2.8.2	✅ Yes
pytest	7.4.3	>=7.4.3	✅ Yes
pytest-flask	1.3.0	>=1.3.0	✅ Yes
flask-debugtoolbar	0.14.1	>=0.14.1	✅ Yes
gunicorn	21.2.0	waitress >=2.1.2	✅ Windows Fix

Testing

After installation, you can verify everything works:

cd E:\LIM
venv\Scripts\activate
python -c "import flask, PIL, fitz; print('All imports successful!')"

If you see "All imports successful!", you're good to go!