Getting Started

Getting Started

This guide will walk you through creating your first PyPositron application.

Prerequisites

• Python 3.9 or higher
• pip (Python package manager)

Installation

Install PyPositron from PyPI:

pip install py-positron

Creating Your First App

Step 1: Create a New Project

Use the PyPositron CLI to create a new project:

positron create

This will start an interactive wizard that will ask you for:

• Project directory: Where to create your project (default: current directory)
• Project name: Name of your project (default: demo_project)
• Author name: Your name (optional)
• Project description: Brief description of your app (optional)
• Virtual environment: Whether to create a virtual environment (recommended)

Step 2: Project Structure

After creation, your project will have the following structure:

your_project/
├── config.json          # Project configuration
├── LICENSE              # MIT License file
├── main/                # Main application directory
│   └── main.py          # Main Python application file
├── views/               # HTML views and static files
│   ├── index.html       # Main HTML template
│   └── checkmark.png    # Example image asset
└── winvenv/            # Virtual environment (Windows, if created)
    └── linuxvenv/      # Virtual environment (Linux, if created)

Step 3: Understanding the Main Files

main/main.py

This is your main Python file:

import py_positron as main

# Run this file by typing positron start on the terminal while at the project root directory.
main.openUI("views/index.html", None, 900, 700, "Example app")
# The app automatically starts - no need to call main.start()
# Go to views to see and edit the HTML file.

views/index.html

This is your HTML interface file - customize it with your own HTML and CSS.

views/checkmark.png

An example image asset included in the default template.

config.json

Contains project configuration including metadata and settings.

Step 4: Run Your App

Navigate to your project directory and start the application:

cd your_project
positron start

This will launch your desktop application in a native window!

Next Steps

• Customize your HTML interface in views/index.html
• Add Python logic to main/main.py
• Learn about the API Reference
• Explore Examples

Tips

1. Virtual Environment: Always use a virtual environment for your projects to avoid package conflicts
2. Development: Make changes to your HTML/CSS files and refresh the app to see changes
3. Python Integration: Use the PyPositron API to integrate Python functionality with your HTML interface

Common Issues

If you encounter any issues, check the Troubleshooting guide or visit our GitHub Issues page.