Streamlit FluSight

This is a toy app for exploring what Streamlit can do and how it works. This code is a learning exercise (i.e., it's not optimized for speed, it's not hosted on anything other than a local machine).)

Installing and running the package (no development)

Because we're not hosting a Streamlit server anywhere, there's no way to run this exploration app without having Python installed on your machine.

Once you've confirmed that your machine has Python >=3.10 installed, you can then use pip to install and run this app locally:

pip install git+https://github.com/reichlab/streamlit-flusight.git
flusight

Setup for local development

The steps below are for setting up a local development environment. This process entails more than just installing the package, because we need to ensure that all developers have a consistent, reproducible environment.

The assumption is that app developers will be using a Python virtual environment that:

is based on the Python version specified in .python-version.
contains the dependency versions specified in the "lockfile" (in this case requirements/requirements-dev.txt).
contains the package installed in "editable" mode.

Clone this repository
Change to the repo's root directory:
```
cd streamlit-flusight
```
Make sure the correct version of Python is currently active, and create a Python virtual environment:
```
python -m venv .venv
```

Activate the virtual environment:

# MacOs/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Install the package dependencies and install the package in editable mode:

python -m pip install -r requirements/requirements-dev.txt && python -m pip install -e .

Run the test suite to confirm that everything is working:
```
python -m pytest
```

Development workflow

Because the package is installed in "editable" mode, you can run the code as though it were a normal Python package, while also being able to make changes and see them immediately. This is especially helpful when importing package components (because you can avoid mucking with the Python path).

Updating dependencies

Prerequisites:

'uv'

Note: using pipx (instead of pip) to install uv is a handy way to ensure that uv is available for all of the Python environments on your machine.

The "lockfile" for this project is simply an annotated requirements.txt that is generated by uv (uv is a replacement for pip-compile, which could also be used). There's also a requirements-dev.txt file that contains dependencies needed for development (e.g., pytest).

While it's possible to use pip freeze to generate a detailed lockfile without a third-party tool like uv, the output of pip freeze doesn't distinguish between direct and indirect dependencies or provide any information about why each dependency is included. This probably doesn't matter for a small project, but on a large project, understanding the dependency graph is critical for resolving conflicts.

Additionally, uv (and pip-compile) are able to use the list of high-level dependencies in pyproject.toml to generate a detailed requirements.txt file, which is a good workflow for keeping everything in sync.

To add a dependency to the project:

Add the dependency to the [dependencies] section of pyproject.toml (or to the dev section of [project.optional-dependencies], if it's a development dependency). Don't pin a specific version, since that will make it harder for people to install the package.

Generate updated requirements files:

uv pip compile pyproject.toml -o requirements/requirements.txt && uv pip compile pyproject.toml --extra dev -o requirements/requirements-dev.txt

# temporary fix to make the app deployable on Streamlit Community Cloud, which expect requirements.txt in the repo root
cp requirements/requirements.txt requirements.txt

Update project dependencies:

Note: This package was originally developed on MacOS. If you have trouble installing the dependencies. uv pip sync has a --python-platform flag that can be used to specify the platform.

# note: requirements-dev.txt contains the base requirements AND the dev requirements
#
# using pip
python -m pip install -r requirements/requirements-dev.txt
#
# alternately, you can use uv to install the dependencies: it is faster and has a
# a handy sync option that will cleanup unused dependencies
uv pip sync requirements/requirements-dev.txt

Opinionated notes on Python tooling

The Python ecosystem is overwhelming! Current opinionated preferences, subject to change:

To install and manage various versions of Python: pyenv + a local .python-version file
To install Python packages that are available from anywhere on the machine, regardless of which Python environment is activated: pipx
To create and manage Python virtual environments: venv.
- I like having the environment packages right there in the project directory
- Everything single third-party tool for managing virtual environments (e.g., poetry, PDM, pipenv) does too much and gets in my way
To generate requirements files from pyproject.toml: 'uv'. I don't usually recommend things this new, but it's orders of magnitude faster than pip-compile.
To install dependencies: uv again (again, mostly due to speed; good old pip is another fine option)
Logging: structlog. I recently stopped fighting Python's built-in logging module and haven't looked back.
Linting and formatting: ruff because it does both and is fast.

reichlab / streamlit-flusight