• Repository: pyshiny-tips-dashboard-express
• Live App: Tips Dashboard (Express)

Run and publish interactive apps using PyShiny Express and GitHub Pages.

This is a teaching version of the app written for clarity and understanding. To contribute, please fork the repository and submit a pull request.

This app uses the Seaborn library to import the tips dataset. The dataset contains 244 records and 7 fields. The fields are:

Column names for the tips dataset include:

• total_bill: the bill amount (dollars)
• tip: the tip amount (dollars)
• sex: Male or Female
• smoker: Yes or No
• day: Day of the week
• time: Lunch or Dinner
• size: Size of the party

See: https://github.com/mwaskom/seaborn-data/blob/master/tips.csv

The tips dataset is a nice, clean dataset with no missing values. Generally, no cleaning or transformation is needed.

From https://shiny.posit.co/py/docs/user-interfaces.html#altogether-now. This version has been modified slightly for hosting with GitHub Pages.

Before you start, have the following installed:

• Python: Install the most recent version from python.org.
• Git: Download and install Git from git-scm.com.
• Visual Studio Code (VS Code): Download from code.visualstudio.com.
• VS Code Extensions: Install the Python extension and the Shiny extension in VS Code.

• Configure Git: Set up your user name and email with Git using the following commands in your terminal. Change the values to your name and email address. This is a one-time setup.

  git config --global user.name "Your Name"
  git config --global user.email "[email protected]"

Commands are operating system-specific. These commands are for Windows users. On Mac/Linux, generally use python3 instead of py. Edit your README.md to reflect the commands that work on your machine.

1. Open project folder in VS Code.
2. Open a new terminal (on Windows, ensure the terminal type is PowerShell (not the old cmd)
3. Run the following commands in the terminal one at a time to verify installations.

py --version
git --version
git config user.name
git config user.email

Run the following commands in the terminal to set up a project virtual environment and install the necessary packages. Run them from the root project folder (e.g. pyshiny-tips-dashboard-express). Use PowerShell on Windows or the terminal on macOS and Linux.

Create a project virtual environment in the .venv folder of the project root directory.

py -m venv .venv

Creating a project virtual environment is generally a one-time setup. Once the folder exists, we can activate it to work on the project.

If VS Code pops up and says: We noticed a new environment has been created. Do you want to select it for the workspace folder? select Yes.

Once the project virtual environment exists, we activate the virtual environment to work on the project - or when we open a new terminal.

On Windows:

.venv\Scripts\Activate

On macOS and Linux:

source .venv/bin/activate

Verify: Generally when the environment is active, (.venv) will appear in the terminal prompt.

We also need to select this project virtual environment in VS Code. To do this:

1. Open the VS Code command palette (Ctrl+Shift+P).
2. Search for "Python: Select Interpreter".
3. Select the .venv folder in the project root directory.

When the project virtual environment is active, install packages into the project virtual environment so they are available for use in the Python code.

NOTE:

• We install packages into the project virtual environment.
• We import packages into Python code (after they have been installed).

First, upgrade pip and setuptools (core packages) for good measure. Then, install the project-specific required packages.

With the project virtual environment active in the terminal, run the following commands:

py -m pip install --upgrade pip setuptools
py -m pip install --upgrade -r requirements.txt

Installing packages is generally a one-time setup.

With your project virtual environment active in the terminal and the necessary packages installed, run the app with live reloading and automatically open it in the browser:

shiny run --reload --launch-browser tips/app.py

While the app is running, that terminal is fully occupied. Open a new terminal to run other commands.

When the app is running, open a browser and navigate to http://127.0.0.1:8000/ to view the app.

Please Be Patient: The app may take a few seconds to start. The charts may take an additional few seconds to render.

With your project virtual environment active in the terminal and the necessary packages installed, remove any existing assets and use shinylive export to build the app in the penguins folder to the docs folder:

shiny static-assets remove
shinylive export tips docs

Optional: Edit docs/index.html to show a custom browser tab title and add a favicon.

    <title>PyShiny Tips</title>
    <link rel="icon" type="image/x-icon" href="./favicon.ico">

After the app is built, serve the app locally from the docs folder to test before publishing to GitHub Pages. In the terminal, run the following command from the root of the project folder with the project virtual environment active:

py -m http.server --directory docs --bind localhost 8008

Open a browser (tested with Chrome) and navigate to http://[::1]:8008/ to view the app running locally.

After editing project files, use Git add/commit/push changes to the main branch of the repository. Note that if a terminal is serving an app, it is not available for other commands. Run the following commands from a new or available terminal to git add/commit/push changes to GitHub. Replace "Your commit message" with a meaningful message about the changes you made to the project files. Run commands one at a time and wait for each to complete before running the next.

git add .
git commit -m "Your commit message"
git push -u origin main

The first time you set up an app, you'll need to navigate to the repository on GitHub and configure the settings to publish the app with GitHub Pages. After configuring the repository once, each time you push changes to the main branch, the app will automatically update.

1. Go to the repository on GitHub and navigate to the Settings tab.
2. Scroll down and click the Pages section.
3. Select branch main as the source for the site.
4. Change from the root folder to the docs folder to publish from.
5. Click Save and wait for the site to build.
6. Edit the "About" section of the repository to include a link to the live app.

Example csv data from tips.csv. Used for review only. In the app, we import the data from the Seaborn library.

The Shiny development team. Shiny for Python [Computer software]. https://github.com/posit-dev/py-shiny

Running the Shiny for Python app locally on port 8000. The third chart is slightly different from the original - it has been tested to run successfully on GitHub Pages.

Serving the static app locally from the docs folder (as GitHub Pages will) on port 8008. The browser tab shows a custom tab title and favicon. Recommended: Build your own favicon at https://favicon.io/.