Preswald Documentation

Preswald is a static-site generator designed for building interactive data applications using Python. It packages compute, data access, and UI into self-contained applications that run locally in the browser using a WASM runtime (Pyodide and DuckDB).

Key characteristics include:

• Local Execution: No server required; apps run offline and can handle large datasets.
• Automatic Reactivity: A reactive engine automatically tracks dependencies in your Python code and triggers minimal updates when data changes.
• File-First Approach: A single command generates a fully-packaged .html application.
• High-Performance Visualization: Supports GPU-accelerated charts via fastplotlib with offscreen acceleration and WebSocket-based streaming.

To start a new project, use the preswald init command followed by your app name. This creates a project directory with a starter structure including hello.py, preswald.toml, and secrets.toml.

To view your app during development, use preswald run to launch a local development server.

preswald init my_app
cd my_app
preswald run

The query function validates source existence, SQL syntax, and handles connection/query errors. Use try-except blocks to catch ValueError for configuration issues or general Exception for query execution errors.

Example:

from preswald import query

try:
    results = query("SELECT * FROM events", 'eq_clickhouse')
except ValueError as e:
    print(f"Configuration error: {e}")
except Exception as e:
    print(f"Query error: {e}")

Use the pw.matplotlib() widget to render Matplotlib plots as images within a card container in your Preswald application. The widget automatically handles the conversion of Matplotlib figures into images.

To display multiple distinct plots, ensure you call plt.figure() before each new plot creation to prevent them from being drawn on the same canvas.

import preswald as pw
import matplotlib.pyplot as plt
import numpy as np

def app():
    # Create a simple plot
    x = np.linspace(0, 10, 100)
    y = np.sin(x)
    
    plt.figure(figsize=(8, 6))
    plt.plot(x, y)
    plt.title('Sine Wave')
    
    pw.matplotlib(_label="My Plot")

pw.run(app)

To ensure reliable data retrieval with get_df, follow these practices:

1. Verify Configuration: Always check if the source_name exists in your preswald.toml before calling the function.
2. Specify Tables for Databases: For PostgreSQL and ClickHouse sources, always provide the table_name.
3. Implement Error Handling: Use try-except blocks to catch configuration and connection errors.
4. Monitor Memory: Be mindful of memory limitations when retrieving very large datasets into a pandas DataFrame.

To resolve dependency errors or version conflicts, isolate your dependencies using a virtual environment.

Using venv

1. Create: python -m venv env
2. Activate (macOS/Linux): source env/bin/activate
3. Activate (Windows): env\Scripts\activate

Using Conda

1. Create: conda create --name myenv python=3.9 (replace myenv and 3.9 as needed)
2. Activate: conda activate myenv

# venv example
python -m venv env
source env/bin/activate

# Conda example
conda create --name myenv python=3.9
conda activate myenv

The get_df function validates source existence, checks for required parameters, and handles connection/query errors. It is recommended to wrap calls in a try-except block to handle ValueError (for configuration issues) or general exceptions (for connection/query issues).

Note: You must call connect() before using get_df.

from preswald import get_df

try:
    df = get_df('eq_pg', 'large_table')
except ValueError as e:
    print(f"Configuration error: {e}")
except Exception as e:
    print(f"Error retrieving data: {e}")

To set up and run a Preswald project, follow these three steps:

1. Configure data connections: Define your data sources and connections within the preswald.toml configuration file.
2. Manage sensitive information: Store passwords, API keys, and other sensitive credentials in a secrets.toml file to keep them out of your main configuration.
3. Execute the application: Use the CLI to start your application.

preswald run

When working with large datasets, use the limit parameter to prevent rendering excessive rows, which improves performance and readability.

table(df, title="First 100 Rows", limit=100)