Cursor Rules for FastLED WASM Project
CRITICAL: Python Command Usage
ALWAYS use uv to run Python code, NOT python or python3!
Command Guidelines:
- ✅ Use:
uv run <script.py>
- ✅ Use:
uv run -m <module>
- ✅ Use:
uv run python <script.py> (if explicitly needed)
- ❌ NEVER use:
python <script.py>
- ❌ NEVER use:
python3 <script.py>
Examples:
- Instead of
python src/fastled/cli.py, use uv run src/fastled/cli.py
- Instead of
python -m pytest, use uv run -m pytest
- Instead of
python3 build_exe.py, use uv run build_exe.py
Rationale:
- This project uses
uv for Python package and environment management
- Using
python or python3 directly may use the wrong Python version or miss dependencies
uv ensures consistent execution with the project's specified Python version and dependencies
Testing:
- Follow the user rule: run unit tests with
bash test
- For manual testing, use
uv run prefix for any Python commands
Development Workflow:
- Use
uv for all Python execution
- Ensure virtual environment is managed by
uv
- Install dependencies with
uv add <package>
- Run scripts with
uv run <script>
Emoji/Emoticon Usage
ALWAYS use the EMO() function for emojis, NEVER hardcode emojis directly!
Guidelines:
- ✅ Use:
from fastled.emoji_util import EMO then EMO('⚠️', 'WARNING:')
- ✅ Use:
from fastled.emoji_util import safe_print for Unicode-safe printing
- ❌ NEVER use: hardcoded emojis like
print("⚠️ Warning")
- ❌ NEVER use: raw Unicode without fallback handling
Common Patterns:
- Warning messages:
EMO('⚠️', 'WARNING:')
- Success messages:
EMO('✅', 'SUCCESS:')
- Error messages:
EMO('❌', 'ERROR:')
- Info messages:
EMO('ℹ️', 'INFO:')
- Playwright/browser:
EMO('🎭', '*')
- Package/install:
EMO('📦', '*')
Rationale:
- Windows cmd.exe has poor Unicode support and will crash on raw emojis
- The
EMO() function provides fallback text for systems that don't support emojis
- Ensures consistent behavior across all platforms (Windows, macOS, Linux)
- Prevents application crashes due to encoding issues
Examples:
# Good - with EMO function
from fastled.emoji_util import EMO
print(f"{EMO('⚠️', 'WARNING:')} Debug mode detected with Playwright installed")
# Bad - hardcoded emoji
print("⚠️ Debug mode detected with Playwright installed")
Additional Rules:
- When suggesting Python commands, always prefix with
uv run
- When creating scripts that execute Python, use
uv run in the script
- When documenting Python usage, emphasize
uv run syntax
- Update any existing scripts that use
python or python3 to use uv run
- When adding user-facing messages with emojis, always use the
EMO() function