Getting Started

Setting up and using hpy-tool is straightforward. Follow these steps to install the tool and initialize your first project.

Installation

A Python virtual environment is strongly recommended to manage dependencies for your project.

# 1. Create and activate a virtual environment (if you haven't)
python -m venv .venv

# Linux/macOS:
source .venv/bin/activate

# Windows (CMD):
# .venv\Scripts\activate.bat

# Windows (PowerShell):
# .venv\Scripts\Activate.ps1

# 2. Install hpy-tool
# Option A: From PyPI (Recommended once published)
# pip install hpy-tool

# Option B: From local source code (for development)
# Navigate to the root directory of the hpy-tool project (where pyproject.toml is)
pip install -e .

# Dependencies: This installs 'watchdog' (required for -w) and 'tomli'
# (required for hpy.toml configuration on Python < 3.11).

Initialize Your First Project

The easiest way to start is by using the --init command.

# 1. Initialize a new project directory
hpy --init my-first-app

# 2. Navigate into the project directory
cd my-first-app

This command will prompt you to choose a template. Choosing the default (Directory with Layout) creates the following structure:

my-first-app/
├── hpy.toml        # Project configuration file
└── src/            # Default source directory
    ├── _layout.hpy   # Shared layout file
    ├── about.hpy     # Example page
    ├── index.hpy     # Example homepage
    └── static/       # Static asset directory
        └── logo.svg  # Example static file

Key files generated:

• hpy.toml: Configures your project's input, output, and static directories.
• src/_layout.hpy: The main HTML template for all pages.
• src/index.hpy, src/about.hpy: Example content pages.
• src/static/logo.svg: An example static asset referenced in the layout.

Important: For static asset handling to work, ensure the static_dir_name line in your hpy.toml is uncommented and correctly set.

Run the Development Server

With your project initialized and dependencies installed, start the development server:

# Make sure you are inside your project directory ('my-first-app')
hpy -w

Explanation:

• hpy: Executes the tool.
• -w (watch mode): This flag tells hpy-tool to:
  • Perform an initial build (compiling .hpy files and copying static assets) based on hpy.toml settings (defaulting to src -> dist).
  • Start a development web server (defaulting to port 8000) serving the output directory (dist).
  • Watch the source directory (src) for changes.
  • Automatically rebuild relevant .hpy files or sync changed static assets when you save changes.

Open your web browser and navigate to http://localhost:8000 (or the port shown in the console). You should see your application running!

Development Workflow

1. Edit files within your source directory (src/ by default). Modify .hpy pages, the layout, or add/change files in the static directory.
2. Save your changes.
3. hpy-tool (running with -w) detects the changes and automatically rebuilds or syncs assets.
4. Refresh your web browser to see the updated application.

You are now ready to start building your web application with HPY!