gen/gen_mpy: Add Python stub file generation for IDE support.

Extends the LVGL bindings generator to automatically create Python stub
files (.pyi) that provide type hints and enable IDE autocompletion for
LVGL MicroPython bindings.

Features:
- Comprehensive type mapping from C types to Python type hints
- Single stub file with all widgets, functions, enums, and constants
- Detailed documentation header with content statistics

The generated lvgl.pyi file includes 40+ widget classes, 300+ functions,
and comprehensive type information for better development experience.

Include C function names, location and description in Python stub docstrings.
The docstrings include a "C function: <name>" line before the
"Source: <file>:<line>" reference. For example:
- Python method `delete()` shows "C function: lv_obj_delete"
- Python method `add_flag()` shows "C function: lv_obj_add_flag"

Create a proper Python package structure for LVGL type stubs:
- Create stubs/pyproject.toml with setuptools-scm versioning
- Add stubs/lvgl-stubs/ package directory with __init__.py and py.typed
- Update gen_mpy.py to output stubs to package directory by default
- Add .gitignore to exclude generated .pyi files but include package structure
- Update README.md with comprehensive IDE support documentation

The stubs package can be installed with 'pip install -e stubs/' for
development or built into a wheel for distribution. Generated stub files
include complete type definitions for all LVGL widgets, functions, and
enums with extracted documentation.

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>

Author: pi-anl

.gitignore

@@ -6,3 +6,17 @@ yacctab.py
 *.bak
 .history
 .vscode
+
+# Python cache files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Build artifacts
+build/
+*.pp
+*.pp.c
+
+# Test files
+test_*/

CLAUDE.md

@@ -0,0 +1,177 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This repository contains MicroPython bindings for LVGL (Light and Versatile Graphics Library). It automatically generates Python bindings from LVGL C headers using the `gen_mpy.py` script, allowing LVGL to be used from MicroPython with native performance.
+
+## Building and Integration
+
+### As a MicroPython User Module
+
+This module is typically used as a git submodule within a MicroPython project. The bindings are built automatically during the MicroPython build process.
+
+**Build Integration:**
+- **Make-based builds**: Uses `micropython.mk` with automatic binding generation
+- **CMake-based builds**: Uses `micropython.cmake` and `mkrules_usermod.cmake`
+- The build system automatically runs `gen/gen_mpy.py` to generate `lv_mpy.c` from LVGL headers
+
+**Key Build Files:**
+- `micropython.mk`: Make-based build rules and LVGL library integration
+- `micropython.cmake`: CMake integration for ESP32/IDF and other platforms
+- `lv_conf.h`: LVGL configuration (affects which bindings are generated)
+
+### Building Standalone (for testing)
+
+From a MicroPython repository with this as a user module:
+
+```bash
+# Unix port (for testing with SDL)
+cd ports/unix
+make USER_C_MODULES=/path/to/lv_binding_micropython/micropython.cmake
+./build-lvgl/micropython
+
+# ESP32 port
+cd ports/esp32
+make USER_C_MODULES=/path/to/lv_binding_micropython/micropython.cmake BOARD=ESP32_GENERIC
+```
+
+## Testing
+
+### Automated Tests
+
+**API Tests** (can be automated/CI):
+```bash
+# From micropython/tests directory
+./run-tests.py ../../lib/lv_binding_micropython/tests/api/basic*.py -r .
+```
+
+**Display Tests** (visual feedback, no interaction):
+```bash
+# From micropython/tests directory  
+./run-tests.py ../../lib/lv_binding_micropython/tests/display/basic*.py -r .
+```
+
+**Interactive Tests** (require user input):
+```bash
+# From micropython/tests directory
+./run-tests.py ../../lib/lv_binding_micropython/tests/indev/basic*.py -r .
+```
+
+### Example Testing
+
+Run all examples and demos:
+```bash
+cd tests
+./run.sh
+```
+
+This runs all Python examples in parallel using GNU parallel, with 5-minute timeouts per test.
+
+## Code Architecture
+
+### Binding Generation System
+
+**Core Components:**
+- `gen/gen_mpy.py`: Main binding generator that parses LVGL headers and generates MicroPython C API
+- `pycparser/`: Modified Python C parser for processing LVGL headers
+- `lvgl/`: Git submodule containing the actual LVGL library
+
+**Generation Process:**
+1. C preprocessor processes LVGL headers with `lv_conf.h` settings
+2. `gen_mpy.py` uses pycparser to parse the preprocessed headers
+3. Generates `lv_mpy.c` containing MicroPython module definitions
+4. Build system compiles everything into the MicroPython binary
+
+### Driver Architecture
+
+**Driver Locations:**
+- `driver/esp32/`: ESP32-specific drivers (ILI9XXX, XPT2046, etc.)
+- `driver/generic/`: Platform-independent Python drivers
+- `driver/linux/`: Linux-specific drivers (evdev, etc.)
+- `driver/stm32/`: STM32-specific drivers
+
+**Driver Types:**
+- **Pure Python**: Easiest to implement, runtime configurable
+- **Pure C**: Best performance, requires rebuild for config changes  
+- **Hybrid**: Critical parts in C, configuration in Python
+
+### Memory Management
+
+- LVGL is configured to use MicroPython's garbage collector
+- Structs are automatically collected when no longer referenced
+- **Important**: Screen objects (`lv.obj` with no parent) are not auto-collected - call `screen.delete()` explicitly
+- Keep references to display and input drivers to prevent premature collection
+
+### Callback System
+
+**Callback Convention**: LVGL callbacks must follow specific patterns to work with MicroPython:
+- Struct containing `void * user_data` field
+- `user_data` passed as first argument to registration function and callback
+- The binding automatically manages `user_data` for MicroPython callable objects
+
+## Development Patterns
+
+### Configuration Management
+
+**Runtime Configuration**: Unlike typical LVGL C drivers, MicroPython drivers should allow runtime configuration:
+
+```python
+# Good - runtime configurable
+from ili9XXX import ili9341
+display = ili9341(dc=32, cs=33, mosi=23, clk=18)
+
+# Avoid - requiring rebuild for pin changes
+```
+
+### Adding New Drivers
+
+1. **Determine driver type** (Pure Python, C, or Hybrid)
+2. **Follow existing patterns** in `driver/` subdirectories
+3. **Make runtime configurable** - avoid hardcoded pins/settings
+4. **Implement standard interface**:
+   - Display drivers: `flush_cb` method or automatic setup
+   - Input drivers: `read_cb` method or automatic setup
+
+### Testing New Features
+
+1. **Add API tests** in `tests/api/` for automated testing
+2. **Add display tests** in `tests/display/` for visual verification  
+3. **Follow existing test patterns** - see `tests/README.md`
+4. **Test on multiple platforms** when possible
+
+## Common Operations
+
+### Regenerating Bindings
+
+If you modify `lv_conf.h` or LVGL headers:
+```bash
+# Clean and rebuild to regenerate bindings
+make clean
+make USER_C_MODULES=/path/to/lv_binding_micropython/micropython.cmake
+```
+
+### Testing Configuration Changes
+
+Use the examples to verify your changes:
+```bash
+# Run a simple test
+./build-lvgl/micropython examples/example1.py
+
+# Or run comprehensive tests
+cd tests && ./run.sh
+```
+
+### Debugging Memory Issues
+
+- Use `gc.collect()` to trigger garbage collection
+- Call `screen.delete()` on screens when done
+- Keep driver references in global variables or long-lived objects
+
+## Integration Notes
+
+- This module requires MicroPython's internal scheduler to be enabled
+- LVGL task handler is called via `mp_sched_schedule` for screen refresh
+- Single-threaded design - LVGL and MicroPython run on same thread
+- Display drivers typically handle event loop setup automatically