troubleshooting - itzmetanjim/py-positron GitHub Wiki

Troubleshooting

This guide helps you solve common issues when working with PyPositron.

Installation Issues

Module Not Found Error

Problem: ModuleNotFoundError: No module named 'py_positron'

Solutions:

  1. Check installation:

    pip show py-positron

  2. Reinstall the package:

    pip uninstall py-positron
pip install py-positron

  3. Check Python environment:

    which python
which pip

  4. Install with --user flag:

    pip install --user py-positron

Permission Errors

Problem: Permission denied during installation

Solutions:

  1. Use --user flag:

    pip install --user py-positron

  2. Use virtual environment:

    python -m venv myenv
# Windows:
myenv\Scripts\activate
# Linux/macOS:
source myenv/bin/activate
pip install py-positron

Dependency Conflicts

Problem: Conflicting package versions

Solutions:

  1. Create fresh virtual environment:

    python -m venv fresh_env
source fresh_env/bin/activate  # or fresh_env\Scripts\activate on Windows
pip install py-positron

  2. Update pip:

    pip install --upgrade pip

CLI Issues

Command Not Found

Problem: 'positron' is not recognized as an internal or external command

Solutions:

  1. Check if Python Scripts directory is in PATH:

    # Windows
echo $env:PATH
# Linux/macOS
echo $PATH

  2. Use python -m instead:

    python -m py_positron.cli create

  3. Reinstall package:

    pip uninstall py-positron
pip install py-positron

Project Creation Fails

Problem: Error during positron create

Solutions:

  1. Check directory permissions:

    • Ensure you have write access to the target directory
    • Try creating in a different location

  2. Check disk space:

    • Ensure sufficient disk space

  3. Run with elevated privileges (if necessary):

    # Windows (run as Administrator)
# Linux/macOS
sudo positron create

Virtual Environment Issues

Problem: Virtual environment creation fails

Solutions:

  1. Manual venv creation:

    cd your_project
python -m venv venv
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

  2. For macOS users:

  3. Check Python version:

    python --version  # Should be 3.9+

Runtime Issues

HTML File Not Found

Problem: FileNotFoundError: HTML file not found

Solutions:

  1. Check file path:

    import os
print(os.path.abspath("views/index.html"))
print(os.path.exists("views/index.html"))

  2. Verify working directory:

    import os
print(os.getcwd())

  3. Use absolute paths:

    import os
html_path = os.path.join(os.path.dirname(__file__), "views", "index.html")
main.openUI(html_path)
# App starts automatically

Window Doesn't Open

Problem: Application starts but no window appears

Solutions:

  1. Check for errors in console:

    • Look for Python error messages

  2. Verify HTML content:

    • Ensure HTML file is valid
    • Check for syntax errors

  3. Test with minimal HTML:

    <!DOCTYPE html>
<html>
<head><title>Test</title></head>
<body><h1>Test</h1></body>
</html>

  4. Check PyWebView dependencies:

    pip install --upgrade pywebview

Python Code in HTML Not Working

Problem: Code in <py> tags doesn't execute

Solutions:

  1. Check for Python syntax errors:

    • Ensure proper indentation
    • Check for missing imports

  2. Verify py tag styling:

    py { display: none; }

  3. Check browser console for errors:

    • Right-click → Inspect → Console

  4. Test with simple code:

    <py>
print("This should appear in console")
document.alert("Hello from Python!")
</py>

Element Not Found Errors

Problem: document.getElementById returns None

Solutions:

  1. Check element ID:

    <button id="my-button">Click me</button>
<py>
button = document.getElementById('my-button')
if button:
    print("Button found!")
else:
    print("Button not found!")
</py>

  2. Ensure DOM is loaded:

    <py>
# Code runs after DOM is loaded
button = document.getElementById('my-button')
</py>

  3. Use setTimeout for delayed execution:

    <py>
import time

def delayed_setup():
    button = document.getElementById('my-button')
    if button:
        button.addEventListener('click', handle_click)

# Run after a small delay
window.setTimeout(delayed_setup, 100)
</py>

Performance Issues

Slow Application Startup

Problem: App takes long time to load

Solutions:

  1. Optimize imports:

    # Import only what you need
from py_positron import openUI
# Note: start() is called automatically by openUI()

  2. Move heavy operations to background:

    import threading

def heavy_task():
    # Long-running operation
    pass

# Run in background
thread = threading.Thread(target=heavy_task)
thread.daemon = True
thread.start()

  3. Minimize HTML file size:

    • Remove unnecessary CSS/JS
    • Optimize images

Memory Usage Issues

Problem: High memory consumption

Solutions:

  1. Clear unused variables:

    del large_data_structure
import gc
gc.collect()

  2. Avoid circular references:

    # Use weak references when needed
import weakref

  3. Monitor memory usage:

    import psutil
import os

process = psutil.Process(os.getpid())
print(f"Memory usage: {process.memory_info().rss / 1024 / 1024:.2f} MB")

Platform-Specific Issues

Windows Issues

Problem: PowerShell execution policy errors

Solution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem: Antivirus blocking application

Solution:

  • Add PyPositron installation directory to antivirus exclusions
  • Add your project directory to exclusions

macOS Issues

Problem: "App can't be opened" security warning

Solutions:

  1. Allow in Security & Privacy:

    • System Preferences → Security & Privacy → General
    • Click "Allow anyway"

  2. Run from Terminal first:

    cd your_project
positron start

Linux Issues

Problem: Missing GUI libraries

Solution:

# Ubuntu/Debian
sudo apt-get install python3-tk python3-dev

# Red Hat/Fedora
sudo dnf install python3-tkinter python3-devel

# Arch Linux
sudo pacman -S tk python-pip

Debugging Tips

Enable Debug Mode

Add debug information to your application:

import logging
logging.basicConfig(level=logging.DEBUG)

import py_positron as main
main.openUI("views/index.html")
# App starts automatically

Console Logging

Add console output to track execution:

<py>
print("Python code executing...")

def debug_function():
    print("Function called!")
    return "Success"

# Test function
result = debug_function()
print(f"Result: {result}")
</py>

Error Handling

Wrap risky code in try-catch blocks:

<py>
try:
    risky_operation()
except Exception as e:
    print(f"Error occurred: {e}")
    import traceback
    traceback.print_exc()
</py>

Check Event Handlers

Debug event handler registration:

<py>
def check_handlers():
    if hasattr(window, '_py_context'):
        handlers = list(window._py_context.event_handlers.keys())
        print(f"Registered handlers: {handlers}")
    else:
        print("No context found")

check_handlers()
</py>

Getting Help

Documentation Resources

  1. Official Documentation: GitHub Wiki
  2. API Reference: API Documentation
  3. Examples: Examples Guide

Community Support

  1. GitHub Issues: Report bugs or ask questions
  2. Discussions: Community discussions

When Reporting Issues

Include the following information:

  1. Environment details:

    • Operating system and version
    • Python version
    • PyPositron version

  2. Error details:

    • Complete error message
    • Stack trace
    • Steps to reproduce

  3. Code samples:

    • Minimal reproducible example
    • Relevant configuration files

Example issue template:

**Environment:**
- OS: Windows 11
- Python: 3.13.0
- PyPositron: 0.0.1.6

**Problem:**
Description of the issue...

**Steps to reproduce:**
1. Run `positron create`
2. Add this code...
3. Error occurs...

**Error message:**

Paste complete error message here


**Code:**
```python
# Minimal example that reproduces the issue


This should help you resolve most common issues with PyPositron. If you encounter a problem not covered here, please check the GitHub issues or create a new one.
⚠️ **GitHub.com Fallback** ⚠️