Project sturcture - itzmetanjim/py-positron GitHub Wiki

Project Structure

This document explains the structure of a PyPositron project and the purpose of each file and directory.

Default Project Structure

When you create a new PyPositron project using positron create, the following structure is generated:

your_project/
├── main_app.py          # Main Python application file
├── config.json          # Project configuration
├── LICENSE              # MIT License file
├── views/               # Frontend assets directory
│   └── index.html       # Main HTML interface file
└── venv/                # Virtual environment (optional)
    ├── Scripts/         # Windows executables
    │   ├── activate.bat # Activation script (Windows)
    │   ├── python.exe   # Python interpreter
    │   └── pip.exe      # Package installer
    └── lib/             # Python packages
        └── site-packages/

File Descriptions

main_app.py

The main entry point of your PyPositron application.

Default Content:

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")
# Go to views to see and edit the HTML file.

Purpose:

  • Initialize the PyPositron application
  • Configure window properties (size, title)
  • Expose Python functions to the frontend
  • Start the application event loop

config.json

Contains project metadata and configuration settings.

Example Content:

{
    "project_name": "my_awesome_app",
    "author": "Your Name",
    "description": "A PyPositron desktop application",
    "entry_file": "main_app.py",
    "has_venv": true,
    "winvenv_executable": "venv/Scripts/python.exe",
    "linuxvenv_executable": "venv/bin/python",
    "positron_version": "0.0.1.6",
    "created_date": "2025-05-25T17:24:00",
    "python_version": "3.13.0"
}

Configuration Options:

  • project_name: Name of your project
  • author: Project author name
  • description: Brief project description
  • entry_file: Main Python file to execute
  • has_venv: Whether project uses virtual environment
  • winvenv_executable: Path to Windows venv Python executable
  • linuxvenv_executable: Path to Linux/macOS venv Python executable
  • positron_version: PyPositron version used to create project
  • created_date: Project creation timestamp
  • python_version: Python version used

LICENSE

MIT license file automatically generated for your project.

views/index.html

The main HTML file that defines your application's user interface.

Default Structure:

<!DOCTYPE html>
<html>
<head>
    <title>Python-Powered App</title>
    <style>
        py { display: none; } /* Hide py elements */
        /* Your CSS styles here */
    </style>
</head>
<body>
    <h1>Congratulations!</h1>
    <p>You have successfully created your first app using PyPositron!</p>
    
    <button id="button">Test button</button>
    
    <py>
    # Python code executed on page load
    import time
    button = document.getElementById('button')
    
    def button_handler():
        print("Button clicked!")
        document.alert("The current time is " + str(time.strftime("%H:%M:%S")))
    
    button.addEventListener('click', button_handler)
    </py>
</body>
</html>

venv/ (Virtual Environment)

Optional isolated Python environment for your project.

Windows Structure:

venv/
├── Scripts/
│   ├── activate.bat     # Activation script
│   ├── deactivate.bat   # Deactivation script
│   ├── python.exe       # Python interpreter
│   ├── pip.exe          # Package installer
│   └── ...
├── Lib/
│   └── site-packages/   # Installed packages
└── pyvenv.cfg           # Environment configuration

Linux/macOS Structure:

venv/
├── bin/
│   ├── activate         # Activation script
│   ├── python           # Python interpreter
│   ├── pip              # Package installer
│   └── ...
├── lib/
│   └── python3.x/
│       └── site-packages/  # Installed packages
└── pyvenv.cfg           # Environment configuration

Organizing Larger Projects

For more complex applications, consider this expanded structure:

your_project/
├── main_app.py          # Main entry point
├── config.json          # Project configuration
├── LICENSE              # License file
├── requirements.txt     # Python dependencies
├── README.md            # Project documentation
├── src/                 # Source code directory
│   ├── __init__.py
│   ├── models/          # Data models
│   │   ├── __init__.py
│   │   └── user.py
│   ├── services/        # Business logic
│   │   ├── __init__.py
│   │   └── api.py
│   └── utils/           # Utility functions
│       ├── __init__.py
│       └── helpers.py
├── views/               # Frontend assets
│   ├── index.html       # Main page
│   ├── about.html       # Additional pages
│   ├── css/             # Stylesheets
│   │   └── style.css
│   ├── js/              # JavaScript files
│   │   └── app.js
│   └── assets/          # Images, fonts, etc.
│       ├── images/
│       └── fonts/
├── tests/               # Test files
│   ├── __init__.py
│   ├── test_models.py
│   └── test_services.py
└── venv/                # Virtual environment

Best Practices

File Organization

  1. Keep main_app.py simple: Use it only for initialization
  2. Organize by feature: Group related files in directories
  3. Use meaningful names: Make file purposes clear from names
  4. Separate concerns: Keep HTML, CSS, and Python in appropriate files

Directory Structure Tips

  1. views/: Store all HTML and frontend assets
  2. src/: Place Python modules and packages
  3. tests/: Keep test files separate
  4. docs/: Add documentation files

Configuration Management

  1. Use config.json: Store project settings centrally
  2. Environment variables: For sensitive data
  3. requirements.txt: List Python dependencies
  4. Version control: Exclude venv/ and sensitive files

Virtual Environment

  1. Always use venv: Isolate project dependencies
  2. Document dependencies: Maintain requirements.txt
  3. Ignore in VCS: Don't commit venv/ to version control

Working with Assets

Static Files

Place static assets in organized subdirectories:

views/
├── index.html
├── css/
│   ├── main.css
│   └── components.css
├── js/
│   ├── app.js
│   └── utils.js
├── images/
│   ├── logo.png
│   └── icons/
└── fonts/
    └── custom-font.woff2

Referencing Assets

In HTML files, use relative paths:

<!-- CSS -->
<link rel="stylesheet" href="css/main.css">

<!-- JavaScript -->
<script src="js/app.js"></script>

<!-- Images -->
<img src="images/logo.png" alt="Logo">

Asset Organization Tips

  1. Use consistent naming: kebab-case for files
  2. Optimize images: Compress for better performance
  3. Version assets: For cache busting when needed
  4. Document usage: Comment asset purposes

Migration and Updates

Upgrading PyPositron

When updating PyPositron versions:

  1. Update the package: pip install --upgrade py-positron
  2. Check config.json for new configuration options
  3. Review changelog for breaking changes
  4. Test application thoroughly

Project Migration

To migrate existing projects:

  1. Create new project structure
  2. Copy source files to appropriate directories
  3. Update config.json with new structure
  4. Test all functionality

This structure provides a solid foundation for PyPositron applications of any size, from simple utilities to complex desktop applications.

⚠️ **GitHub.com Fallback** ⚠️