docs: cancel PyPI wheel task and add future vision for Python extension architecture

Task #70 Analysis:
- Discovered fundamental incompatibility with PyPI distribution
- McRogueFace embeds CPython rather than being loaded by it
- Traditional wheels expect to extend existing Python interpreter
- Current architecture is application-with-embedded-Python

Decisions:
- Cancelled PyPI wheel preparation as out of scope for Alpha
- Cleaned up attempted packaging files (pyproject.toml, setup.py, etc.)
- Identified better distribution methods (installers, package managers)

Added Future Vision:
- Comprehensive plan for pure Python extension architecture
- Would allow true "pip install mcrogueface" experience
- Requires major refactoring to invert control flow
- Python would drive main loop with C++ performance extensions
- Unscheduled but documented as long-term possibility

This clarifies the architectural boundaries and sets realistic
expectations for distribution methods while preserving the vision
of what McRogueFace could become with significant rework.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
John McCardle 2025-07-08 10:09:37 -04:00
parent d0e02d5b83
commit e34d4f967e
1 changed files with 82 additions and 4 deletions

View File

@ -290,9 +290,9 @@ Rendering Layer:
**Goal**: Ready for the world
```
1. ✅ #85 - Replace all "docstring" placeholders [COMPLETED 2025-07-08]
2. #86 - Add parameter documentation
3. #108 - Generate .pyi type stubs for IDE support
4. #70 - PyPI wheel preparation
2. #86 - Add parameter documentation [COMPLETED 2025-07-08]
3. #108 - Generate .pyi type stubs for IDE support [COMPLETED 2025-07-08]
4. #70 - PyPI wheel preparation [CANCELLED - Architectural mismatch]
5. API reference generator tool
```
@ -535,4 +535,82 @@ Rendering Layer:
---
*Last Updated: 2025-07-05*
## 🔮 FUTURE VISION: Pure Python Extension Architecture
### Concept: McRogueFace as a Traditional Python Package
**Status**: Unscheduled - Long-term vision
**Complexity**: Major architectural overhaul
Instead of being a C++ application that embeds Python, McRogueFace could be redesigned as a pure Python extension module that can be installed via `pip install mcrogueface`.
### Technical Approach
1. **Separate Core Engine from Python Embedding**
- Extract SFML rendering, audio, and input into C++ extension modules
- Remove embedded CPython interpreter
- Use Python's C API to expose functionality
2. **Module Structure**
```
mcrfpy/
├── __init__.py # Pure Python coordinator
├── _core.so # C++ rendering/game loop extension
├── _sfml.so # SFML bindings
├── _audio.so # Audio system bindings
└── engine.py # Python game engine logic
```
3. **Inverted Control Flow**
- Python drives the main loop instead of C++
- C++ extensions handle performance-critical operations
- Python manages game logic, scenes, and entity systems
### Benefits
- **Standard Python Packaging**: `pip install mcrogueface`
- **Virtual Environment Support**: Works with venv, conda, poetry
- **Better IDE Integration**: Standard Python development workflow
- **Easier Testing**: Use pytest, standard Python testing tools
- **Cross-Python Compatibility**: Support multiple Python versions
- **Modular Architecture**: Users can import only what they need
### Challenges
- **Major Refactoring**: Complete restructure of codebase
- **Performance Considerations**: Python-driven main loop overhead
- **Build Complexity**: Multiple extension modules to compile
- **Platform Support**: Need wheels for many platform/Python combinations
- **API Stability**: Would need careful design to maintain compatibility
### Implementation Phases (If Pursued)
1. **Proof of Concept**: Simple SFML binding as Python extension
2. **Core Extraction**: Separate rendering from Python embedding
3. **Module Design**: Define clean API boundaries
4. **Incremental Migration**: Move systems one at a time
5. **Compatibility Layer**: Support existing games during transition
### Example Usage (Future Vision)
```python
import mcrfpy
from mcrfpy import Scene, Frame, Sprite, Grid
# Create game directly in Python
game = mcrfpy.Game(width=1024, height=768)
# Define scenes using Python classes
class MainMenu(Scene):
def on_enter(self):
self.ui.append(Frame(100, 100, 200, 50))
self.ui.append(Sprite("logo.png", x=400, y=100))
def on_keypress(self, key, pressed):
if key == "ENTER" and pressed:
self.game.set_scene("game")
# Run the game
game.add_scene("menu", MainMenu())
game.run()
```
This architecture would make McRogueFace a first-class Python citizen, following standard Python packaging conventions while maintaining high performance through C++ extensions.
---
*Last Updated: 2025-07-08*