# Streamlit Interface

## About

PAA can package and run Streamlit apps from installed packages and local app files.
Core dependency used under the hood: [Streamlit](https://docs.streamlit.io/).
For package Streamlit apps, PAA expects one app file per package, with filename matching the package/module name.
For cross-component preflight checks before packaging, see `concepts/prepackaging_todo.md`.

## Quick Start

### 1. Initialize Streamlit app scaffold

```bash
paa init-streamlit your-package-1
```

This creates `streamlit/your_package_1.py` (or configured `streamlit_dir`).

### 2. Initialize Streamlit config scaffold

```bash
paa init-streamlit-config
```

This creates `.paa.streamlit.config`.

### 3. Run Streamlit app from package

```bash
paa run-streamlit --package your-package-1
```

### 4. Run Streamlit app from file

```bash
paa run-streamlit --path ./streamlit/your_package_1.py
```

## Operational Commands

Initialize Streamlit app scaffold:

```bash
paa init-streamlit your-package-1
```

Initialize Streamlit config:

```bash
paa init-streamlit-config
```

Run app from packaged module:

```bash
paa run-streamlit --package your-package-1
```

Run app from local file:

```bash
paa run-streamlit --path ./streamlit/your_package_1.py
```

## Python File Layout

- path: `streamlit/<module_name>.py` (or configured `streamlit_dir`)
- expected structure:
  - streamlit import
  - package import
  - page content definitions

Recommended scaffold layout:

```python
import streamlit as st
from your_package_1 import *

st.set_page_config(page_title="your-package-1", layout="wide")
st.title("your-package-1 app")
st.caption("Generated by `paa init-streamlit`.")
st.write("Status: ok")
```

## Optional `.paa.streamlit.config`

```yaml
server:
  headless: true
  port: 8501
  address: "0.0.0.0"

theme:
  base: "light"
```

What to edit:
- `server.address` and `server.port` for target environment
- `theme` keys to align with preferred UI defaults

## Importing From Package

Default import style for Streamlit modules:
- `from <package> import *`

Guidance:
- import from packaged module namespace, not PPR component file paths.
- keep expensive setup out of global import scope when possible.

## Notes

- `run-streamlit` can use package source (`--package`) or file source (`--path`).
- app config is optional; default path is `.paa.streamlit.config`.
- Imports from the package Streamlit file are included in dependency extraction during packaging, similar to the main module.
