diff --git a/app.png b/app.png new file mode 100644 index 0000000000000000000000000000000000000000..ed82dfbd1b47335e4a459160784354cd4ab0a4b5 Binary files /dev/null and b/app.png differ diff --git a/data/deploy/_index.md b/data/deploy/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..73226c95fb12b7aefc3365b0ac123ccaaa10f382 --- /dev/null +++ b/data/deploy/_index.md @@ -0,0 +1,35 @@ +--- +title: Deploy +slug: /deploy +--- + +# Deploy + +Get all the information you need to deploy your app and share it with your users. + + + Understand the basics of app deployment. + Deploy your app on our free platform and join a community of developers who share their apps around the world. + Deploy your app in Snowflake for a secure, enterprise-grade environment. + Learn how to deploy your app on a variety of platforms with our convenient collection of tutorials. + diff --git a/data/deploy/community-cloud/_index.md b/data/deploy/community-cloud/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..b7f4d34b629bdfe1c82d237a0c3647113cb94047 --- /dev/null +++ b/data/deploy/community-cloud/_index.md @@ -0,0 +1,45 @@ +--- +title: Streamlit Community Cloud +slug: /deploy/streamlit-community-cloud +--- + +# Welcome to Streamlit Community Cloud + +Deploy, manage, and share your Streamlit apps with the world in minutes — all for free. Your Streamlit Community Cloud account connects directly to your GitHub repository (public or private). Most apps will launch in only a few minutes. Streamlit Community Cloud handles all of the containerization so all you need to worry about is creating the app. Rapidly prototype, explore, and update apps by simply changing your code in GitHub. Most changes appear immediately! + +Want to avoid the work of setting up a local development environment? Community Cloud can help you quickly configure a codespace to develop in the cloud. Whether it's your own deployed app or an app deployed from a public repository, it only takes a few clicks to start coding or editing a Streamlit app. See [Edit your app](/deploy/streamlit-community-cloud/manage-your-app/edit-your-app). + +If you haven't built your first Streamlit app yet, you can check out [Get started](/get-started) in our Streamlit library documentation or [Fork and edit a public app](/deploy/streamlit-community-cloud/get-started/fork-and-edit-a-public-app) from our App gallery. Check out [Community Cloud quickstart](/deploy/streamlit-community-cloud/get-started) to speed-run you through creating your account, deploying an example app, and editing it using GitHub Codespaces. + + + Learn about Streamlit Community Cloud accounts and how to create one. + A step-by-step guide on how to get your app deployed. + Access logs, reboot apps, set favorites, and more. Jump into a GitHub Codespace to edit your app in the cloud. + Share or embed your app. + Update your email, manage connections, or delete your account. + diff --git a/data/deploy/community-cloud/deploy-your-app/_index.md b/data/deploy/community-cloud/deploy-your-app/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..1752c7a3cc7dc456c3f313852f558af434a70d0b --- /dev/null +++ b/data/deploy/community-cloud/deploy-your-app/_index.md @@ -0,0 +1,132 @@ +--- +title: Deploy your app +slug: /deploy/streamlit-community-cloud/deploy-your-app +--- + +# Deploy your app + +Streamlit Community Cloud lets you deploy your apps in just one click, and most apps will deploy in only a few minutes. If you don't have an app ready to deploy, fork or clone one from our App gallery — you can find apps for machine learning, data visualization, data exploration, A/B testing and more. You can also fork and deploy samples straight from the [New app button](/deploy/streamlit-community-cloud/get-started/explore-your-workspace#new-app-button). Once you've deployed your app, check out how you can [Edit your app with GitHub Codespaces](/deploy/streamlit-community-cloud/manage-your-app/edit-your-app#edit-your-app-with-github-codespaces). + + + +If you want to deploy your app on a different cloud service, check out the [Deploy Streamlit apps](/deploy/tutorials) article in our Knowledge Base. + + + +## Add your app to GitHub + +Streamlit Community Cloud launches apps directly from your GitHub repo, so your app code and dependencies need to be on GitHub before you try to deploy your app. For more information on how to specify dependencies, see [App dependencies](/deploy/streamlit-community-cloud/deploy-your-app/app-dependencies). + +Your directory structure should look similar to this: + +``` +your-repository/ +├── your_app.py +└── requirements.txt +``` + +If you are including any custom [Configuration](/develop/concepts/configuration) or [Theming](/develop/concepts/configuration/theming), make sure your config file is saved relative to the root of your repo. Within your repo, your config file should be named `.streamlit/config.toml`. + +``` +your-repository/ +├── .streamlit/ +│ └── config.toml +├── your_app.py +└── requirements.txt +``` + + + +Although you can deploy multiple apps from the same repository, there can be only one configuration file. + + + +## Deploy your app + +1. From your workspace at share.streamlit.io, click "**New app**" from the upper-right corner of your workspace. + + ![Deploy a new app from your workspace](/images/streamlit-community-cloud/deploy-empty-new-app.png) + +2. Fill in your repo, branch, and file path. As a shortcut, you can also click "**Paste GitHub URL**" to paste a link directly to `your_app.py` on GitHub. + + An app URL with a random hash is prefilled but you can change this to a custom subdomain instead. In the example below, the app would be deployed to `https://red-balloon.streamlit.app/`. You can always change your subdomain later. See more about [Custom subdomains](#custom-subdomains) at the end of this page. + + ![Fill in your app's information to deploy your app](/images/streamlit-community-cloud/deploy-an-app.png) + +## Advanced settings for deployment + + + +Streamlit Community Cloud supports all released [versions of Python that are still receiving security updates](https://devguide.python.org/versions/). Streamlit Community Cloud defaults to version 3.9. You can select a version of your choice from the "Python version" dropdown in the "Advanced settings" modal. If an app is running a version of Python that becomes unsupported, it will be forcibly upgraded to the oldest, supported version of Python and may break. + + + +3. (Optional) If you are connecting to a data source or want to specify the Python version for your app, you can do that by clicking "**Advanced settings**" before you deploy the app. Learn more about [Secrets management](/deploy/streamlit-community-cloud/deploy-your-app/secrets-management). + + ![Advanced settings for deploying your app](/images/streamlit-community-cloud/deploy-an-app-advanced.png) + +## Watch your app launch + +Your app is now deploying and you can watch while it launches. Most apps take only a couple of minutes to deploy, but if your app has a lot of dependencies it may take longer to deploy the first time. After the initial deployment, any change that does not touch your dependencies should show up immediately. + +![Watch your app launch](/images/streamlit-community-cloud/deploy-an-app-provisioning.png) + + + +The Streamlit Community Cloud logs on the right hand side of your app are only viewable to users with developer access to your repository. These logs help you debug any issues with the app. Learn more about [Streamlit Community Cloud logs](/deploy/streamlit-community-cloud/manage-your-app#streamlit-community-cloud-logs). + + + +## Your app URL + +That's it — you're done! Your app now has a unique subdomain URL that you can share with others. Read more about how to [Share your app](/deploy/streamlit-community-cloud/share-your-app) with viewers. + +### Unique subdomains + +If the "**Custom subdomain (optional)**" field is blank when you deploy your app, a URL is assigned following a structure based on your GitHub repo. The URL begins with your GitHub username or organization owning your repo, followed by your repo name, app path, and a short hash. If you deploy from a branch other than `main` or `master`, the URL also includes the branch name. + +```bash +https://[GitHub username or organization]-[repo name]-[app path]-[branch name]-[short hash].streamlit.app +``` + +For example, this is an app deployed from the `streamlit` organization. The repo is `demo-self-driving` and the app name is `streamlit_app.py` in the root directory. The branch name is `master` and therefore not included. + +```bash +https://streamlit-demo-self-driving-streamlit-app-8jya0g.streamlit.app +``` + +### Custom subdomains + +Setting a custom subdomain makes it much easier to share your app since you can choose something memorable. Whether you set a custom subdomain during deployment or later, your app's URL will appear as: + +```bash +https://.streamlit.app +``` + +To view or customize your app subdomain from the dashboard: + +1. Click the overflow icon (more_vert) to the app's right and select "**Settings**". + +
+ Streamlit Community Cloud app settings +
+ +2. View the "**General**" tab in the App settings modal. Your app's unique subdomain will appear here. + +
+ Streamlit Community Cloud general app settings +
+ +3. Pick a custom subdomain between 6 and 63 characters in length for your app's URL and hit "**Save**". + +
+ New custom subdomain for your app +
+ +It's that simple! You can then access your app by visiting your customized URL 🎉. + +If a custom subdomain is not available (e.g. because it's already taken), you'll see an error message like this: + +
+ Invalid custom subdomain for your app +
diff --git a/data/deploy/community-cloud/deploy-your-app/app-dependencies.md b/data/deploy/community-cloud/deploy-your-app/app-dependencies.md new file mode 100644 index 0000000000000000000000000000000000000000..b9a865df8b49e7b70e88c466f13ef4cc2b5a0991 --- /dev/null +++ b/data/deploy/community-cloud/deploy-your-app/app-dependencies.md @@ -0,0 +1,111 @@ +--- +title: App dependencies +slug: /deploy/streamlit-community-cloud/deploy-your-app/app-dependencies +--- + +# App dependencies + +The main reason that apps fail to build properly is because Streamlit Community Cloud can't find your dependencies! There are two kinds of dependencies your app might have: Python dependencies and external dependencies. Python dependencies are other Python packages (just like Streamlit!) that you `import` into you script. External dependencies are less common, but they include any other software your script needs to function properly. Since Streamlit Community Cloud runs on Linux, these will be Linux dependencies installed with `apt-get` outside the Python environment. + +For your dependencies to be installed correctly, make sure you: + +1. Add a [requirements file](#add-python-dependencies) for Python dependencies. +2. (optional) Add a `packages.txt` file to manage any external dependencies. + + + +Python requirements files should be placed either in the root of your repository or in the same +directory as your Streamlit app. + + + +## Add Python dependencies + +With each `import` statement in your script, you are bringing in a Python dependency. You need to tell Streamlit Community Cloud how to install those dependencies through a Python package manager. We recommend using a `requirements.txt` which is based on `pip`. + +You should _not_ include built-in Python libraries like `math` or `random` in your `requirements.txt` file. These are a part of Python and aren't installed separately. Also, Streamlit Community Cloud has `streamlit` installed by default. You don't strictly need to include `streamlit` unless you want to pin or restrict the version. If you deploy an app without a `requirements.txt` file, your app will run in an environment with just `streamlit` (and its dependencies) installed. + +If you have a script like the following, no extra dependencies would be needed since `pandas` and `numpy` are installed as direct dependencies of `streamlit`. Similarly, `math` and `random` are built into Python. + +```python +import streamlit as st +import pandas as pd +import numpy as np +import math +import random + +st.write('Hi!') +``` + +However, a valid `requirements.txt` file would be: + +```none +streamlit +pandas +numpy +``` + +Alternatively, if you needed to specify certain versions, another valid example would be: + +```none +streamlit==1.24.1 +pandas>2.0 +numpy<=1.25.1 +``` + +In the above example, `streamlit` is pinned to version `1.24.1`, `pandas` must be strictly greater than version 2.0, and `numpy` must be at-or-below version 1.25.1. Each line in your `requirements.txt` file is effectively what you would like to `pip install` into your cloud environment. + + + +We recommend that you use the latest version of Streamlit to ensure full Streamlit Community Cloud functionality. Be sure to take note of Streamlit's [current requirements](https://github.com/streamlit/streamlit/blob/develop/lib/setup.py) for package compatibility when planning your environment, especially `protobuf>=3.20,<5`. + + + +If you pin `streamlit` below 1.20.0, you may experience unexpected results if you've pinned any dependencies of `altair`. If `streamlit` is installed below version 1.20.0, `altair<5` will be reinstalled on top of your environment for compatibility reasons. When this happens all of altair's dependencies will be updated. + +### Other Python package managers + +There are other Python package managers besides `pip`. If you want to consider alternatives to using a `requirements.txt` file, Streamlit Community Cloud will look for other Python dependency managers to use in the order below. Streamlit will stop and install the first dependency file found. + + + + + + + + + + + + + + + + + + + + + + +
Recognized FilenamePython Package Manager
Pipfilepipenv
environment.ymlconda
requirements.txtpip
pyproject.tomlpoetry
+ + + +You should only use one requirements file for your app. If you include more than one (e.g. `requirements.txt` and `Pipfile`), only the first file encountered will be used as described above. Additionally, Streamlit will first look in the directory of your Streamlit app; however, if no requirements file is found, Streamlit will then look at the root of the repo. + + + +## apt-get dependencies + +For many apps, a `packages.txt` file is not required. However, if your script requires any software to be installed that is not a Python package, then you will need a `packages.txt` file. Streamlit Community Cloud is built on Debian Linux. Anything you would like to `apt-get install` needs to go in your `packages.txt` file. + +If `packages.txt` exists in the root directory of your repository we automatically detect it, parse it, and install the listed packages. You can read more about apt-get in Linux documentation. + +Add **apt-get** dependencies to `packages.txt` — one package name per line. For example, mysqlclient is a Python package which requires additional software be installed to function. A valid `packages.txt` file to enable `mysqlclient` would be: + +```bash + build-essential + pkg-config + default-libmysqlclient-dev +``` diff --git a/data/deploy/community-cloud/deploy-your-app/secrets-management.md b/data/deploy/community-cloud/deploy-your-app/secrets-management.md new file mode 100644 index 0000000000000000000000000000000000000000..c6e6398a1c22fbcec7e21dc09797161b626694d7 --- /dev/null +++ b/data/deploy/community-cloud/deploy-your-app/secrets-management.md @@ -0,0 +1,117 @@ +--- +title: Secrets management +slug: /deploy/streamlit-community-cloud/deploy-your-app/secrets-management +--- + +# Secrets management + +## Introduction + +If you are [connecting to data sources](/develop/tutorials/databases), you will likely need to handle credentials or secrets. It's generally considered bad practice to store unencrypted secrets in a git repository. If your application needs access to sensitive credentials the recommended solution is to store those credentials in a file that is not committed to the repository and to pass them as environment variables. + +Secrets management allows you to store secrets securely and access them in your Streamlit app as environment variables. + +## How to use Secrets Management + +### Deploy an app and set up secrets + +1. From your worksapce at share.streamlit.io, click "**New app**". +2. Fill out your app's information and click "**Advanced settings...**" + + ![Access advanced settings when deploying your app](/images/streamlit-community-cloud/deploy-an-app-advanced-settings.png) + +3. A modal will appear with an input box for your secrets. + + ![Save your secrets in advanced settings when deploying your app](/images/streamlit-community-cloud/deploy-an-app-advanced.png) + +4. Provide your secrets in the "Secrets" field using TOML format. For example: + + ```toml + # Everything in this section will be available as an environment variable + db_username = "Jane" + db_password = "12345qwerty" + + # You can also add other sections if you like. + # The contents of sections as shown below will not become environment + # variables, but they'll be easily accessible from within Streamlit anyway + # as we show later in this doc. + [my_cool_secrets] + things_i_like = ["Streamlit", "Python"] + ``` + +### Use secrets in your app + +Access your secrets as environment variables or by querying the `st.secrets` dict. For example, if you enter the secrets from the section above, the code below shows you how you can access them within your Streamlit app. + +```python +import streamlit as st +import os + +# Everything is accessible via the st.secrets dict: +st.write("DB username:", st.secrets["db_username"]) +st.write("DB password:", st.secrets["db_password"]) +st.write("My cool secrets:", st.secrets["my_cool_secrets"]["things_i_like"]) + +# And the root-level secrets are also accessible as environment variables: +st.write( + "Has environment variables been set:", + os.environ["db_username"] == st.secrets["db_username"], +) +``` + + + +You can access `st.secrets` via attribute notation (e.g. `st.secrets.key`) or key notation (e.g. `st.secrets["key"]`) — just like [`st.session_state`](/develop/api-reference/caching-and-state/st.session_state). + + + +You can even use TOML sections to compactly pass multiple secrets as a single attribute. + +Consider the following secrets: + +```toml +[db_credentials] +username = "my_username" +password = "my_password" +``` + +Rather than passing each secret as attributes in a function, you can more compactly pass the section to achieve the same result. You can use Python's unpacking notation like the following example which uses the secrets above: + +```python +# Verbose version +my_db.connect(username=st.secrets.db_credentials.username, password=st.secrets.db_credentials.password) + +# Far more compact version! +my_db.connect(**st.secrets.db_credentials) +``` + +### Edit your app's secrets + +If you need to add or edit your secrets for an app that is already deployed, you can access advanced setting from your admin panel. + +1. Go to share.streamlit.io. +2. Click the overflow menu icon (more_vert) for your app. +3. Click "**Settings**". + ![Access your app settings from your workspace](/images/streamlit-community-cloud/workspace-app-settings.png) +4. A modal will appear. Click "**Secrets**" on the left. + ![Access your secrets through your app settings](/images/streamlit-community-cloud/workspace-app-settings-secrets.png) +5. After you edit your secrets, click "**Save**". It might take a minute for the update to be propagated to your app, but the new values will be reflected when the app re-runs. + +### Develop locally with secrets + +When developing your app locally, add a file called `secrets.toml` in a folder called `.streamlit` at the root of your app repo, and copy/paste your secrets into that file. Further instructions are available in the Streamlit library [Secrets management](/develop/concepts/connections/secrets-management) documentation. + + + +Be sure to add this file to your `.gitignore` so you don't commit your secrets! + + + +```bash +your-LOCAL-repository/ +├── .streamlit/ +│ ├── config.toml +│ └── secrets.toml # Make sure to gitignore this! +├── your_app.py +└── requirements.txt +``` diff --git a/data/deploy/community-cloud/get-started/_index.md b/data/deploy/community-cloud/get-started/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..b4fb6c59556827ea49bdcf1642d3093653476ca7 --- /dev/null +++ b/data/deploy/community-cloud/get-started/_index.md @@ -0,0 +1,36 @@ +--- +title: Get started with Streamlit Community Cloud +slug: /deploy/streamlit-community-cloud/get-started +--- + +# Get started with Streamlit Community Cloud + +Welcome to Streamlit Community Cloud, where you can share your Streamlit apps with the world! Whether you've already created your first Streamlit app or you're just getting started, you're in the right place. + +First things first, you need to create your Streamlit Community Cloud account to start deploying apps. + + + + + + + +If you're looking for help to build your first Streamlit app, read our [Get started](/get-started) docs for the Streamlit library. If you want to fork an app and start with an example, check out our App gallery. Either way, it only takes a few minutes to create your first app. diff --git a/data/deploy/community-cloud/get-started/connect-github.md b/data/deploy/community-cloud/get-started/connect-github.md new file mode 100644 index 0000000000000000000000000000000000000000..09b00a878de1855fc0b423fcd87c39989660a464 --- /dev/null +++ b/data/deploy/community-cloud/get-started/connect-github.md @@ -0,0 +1,74 @@ +--- +title: Connect your GitHub account +slug: /deploy/streamlit-community-cloud/get-started/connect-your-github-account +--- + +# Connect your GitHub account + +Connecting GitHub to your Streamlit Community Cloud account allows you to deploy apps directly from the files you store in your repos. It also lets the system check for updates to those files and automatically update your app. There are two stages to this authorization: the first happens when you connect your account for the first time and the second happens when you deploy your first app. + +Everyone is prompted to connect GitHub when they create an account. If you need to connect GitHub to an existing primary identity, see [Manage your GitHub connection](/deploy/streamlit-community-cloud/manage-your-account/manage-your-github-connection). + +This page contains additional information about the authorization needed to connect GitHub. If you have just created your account, you are free to skip ahead and [Explore your workspace](/deploy/streamlit-community-cloud/get-started/explore-your-workspace). GitHub's authorization prompts occur automatically as needed. + +## Authorize your GitHub account + +There are two different authorization prompts to grant access between Streamlit and your GitHub account. The first authorization—"Authorize Streamlit"—happens when you connect your GitHub account to Streamlit. The second authorization—"Streamlit is requesting additional permissions"—happens when you deploy your first app. You must click "**Authorize streamlit**" on both. If you are a member of any GitHub organizations, read below to understand the extras steps to [authorize an organization](#organization-access). Questions about GitHub permissions? Read some frequently asked questions about our [GitHub integration](/deploy/streamlit-community-cloud/troubleshooting#github-integration). + +Authorize your GitHub account + + + +You must have **admin** permissions to your repo in order to deploy apps. If you don't have admin access, talk to the repo's owner or reach out to us on the Community forum. + + + +## Organization access + +If you are working in a repository that is owned by an organization, authorization must be granted by that organization. If you are an owner or member of a GitHub organization when you connect your GitHub account, your authorization prompts will include an extra section labeled "Organization access". + +### Organizations you own + +For any organization you own, if authorization has not been previously granted or denied you can click "**Grant**" before you click "**Authorize streamlit**". + +Authorize your Streamlit on a GitHub organization you own + +### Organizations owned by others + +For an organization you don't own, if authorization has not been previously granted or denied you can click "**Request**" before you click "**Authorize streamlit**". + +
+Authorize your Streamlit on a GitHub organization owned by others +
+ +### Previous or pending authorization + +If someone has already started the process of authorizing Streamlit for your organization, different options and statuses will display accordingly. + +#### Approved access + +If an organization has already granted Streamlit access, a green check is shown. + +
+Approved authorization for Streamlit on an organization +
+ +#### Pending access + +If a request has been previously sent but not yet approved, a pending status shows. + +
+Pending authorization for Streamlit on an organization +
+ +#### Denied access + +If a request has been previously sent and denied, no option to grant or request access is shown. In this case, the organization owner will need to authorize Streamlit from GitHub. See GitHub's documentation on OAuth apps and organizations. + +
+Denied authorization for Streamlit on an organization +
+ +## What's next? + +Now that you have your account you can [Explore your workspace](/deploy/streamlit-community-cloud/get-started/explore-your-workspace). Or if you're ready to go, jump right in and [Deploy your app](/deploy/streamlit-community-cloud/deploy-your-app). diff --git a/data/deploy/community-cloud/get-started/create-your-account.md b/data/deploy/community-cloud/get-started/create-your-account.md new file mode 100644 index 0000000000000000000000000000000000000000..db9c26f1cfafe43fb27864ff8560b1638e122349 --- /dev/null +++ b/data/deploy/community-cloud/get-started/create-your-account.md @@ -0,0 +1,122 @@ +--- +title: Create your account +slug: /deploy/streamlit-community-cloud/get-started/create-your-account +--- + +# Create your account + +Before you can start deploying apps for the world to see, you need to sign up for your Streamlit Community Cloud account. + +![Sign up: Get started with Streamlit Community Cloud](/images/streamlit-community-cloud/sign-up.png) + +Streamlit Community Cloud accounts have two underlying identities: primary and source control. Your primary identity is used for viewing analytics as well as viewing permissions. Your source-control identity is used for deploying and managing apps. + +## Sign up + +Although you can begin the sign-up process with GitHub, we recommend starting with Google or email in order to have a complete account from the start. + +- [Step 1: Primary identity](#step-1-primary-identity) (Google or email) +- [Step 2: Source control](#step-2-source-control) (GitHub) +- [Step 3: Set up your account](#step-3-set-up-your-account) + +### Step 1: Primary identity + +Your primary identity is associated to an email. You can sign in through Google or through single-use, emailed links which are valid for 15 minutes once requested. + +If you're sharing a private app, you will assign viewing permission by email. Therefore, your app's users will need to sign in with either Google or emailed links. + +#### Primary identity option 1: Google + +1. Go to share.streamlit.io/signup. +2. Click "**Continue with Google**". + +
+Sign up for Streamlit Community Cloud with Google +
+ +3. Enter your Google credentials and click "**Next**". + +
+Enter your Google credentials +
+ +4. If you will be deploying or managing any apps, click "**Connect GitHub account**" and proceed to [Step 2: Source Control](/deploy/streamlit-community-cloud/get-started/create-your-account#step-2-source-control). If you are only going to be viewing apps and will not be using GitHub, you can click "**Skip this step**" and proceed to [Step 3: Set up your account](#step-3-set-up-your-account). + +
+Connect your GitHub account to Streamlit Community Cloud +
+ +#### Primary identity option 2: email + +1. Go to share.streamlit.io/signup. +2. Enter your email address and click "**Continue with email**". + +
+Sign up for Streamlit Community Cloud with email +
+ +3. A confirmation screen will display, telling you to check your email. + +
+Streamlit Community Cloud confirmation to check your email +
+ +4. Check your inbox for an email with the subject "Sign in to Streamlit Cloud". Click the link to sign in. + +
+Streamlit Community Cloud sign-in email +
+ +5. If you will be deploying or managing any apps, click "**Connect GitHub account**" and proceed to [Step 2: Source control](/deploy/streamlit-community-cloud/get-started/create-your-account#step-2-source-control). If you are only going to be viewing apps and will not be using GitHub, you can click "**Skip this step**" and proceed to [Step 3: Set up your account](#step-3-set-up-your-account). + +
+Connect your GitHub account to Streamlit Community Cloud +
+ +### Step 2: Source control + +Streamlit Community Cloud is integrated with GitHub for source control. If you begin your sign-up process with GitHub, you will not be directly prompted to create a primary identity. However, you can attach a Google account later. + +There are two different authorization requests to completely [Connect your GitHub account](/deploy/streamlit-community-cloud/get-started/connect-your-github-account). You will encounter the first authorization request when you begin connecting your GitHub account. A second authorization is needed the first time you deploy an app. If you will be deploying or managing any apps from a GitHub organization, your authorization requests will include additional options to allow [Organization access](/deploy/streamlit-community-cloud/get-started/connect-github#organization-access). + +1. After completing [Step 1: Primary identity](#step-1-primary-identity) or after clicking "**Continue with GitHub**" from the sign-up page, enter your GitHub credentials and click "**Sign in**". + +
+Enter your GitHub credentials +
+ +2. Click "**Authorize streamlit**". + +
+Authorize streamlit to connect to your GitHub account +
+ +3. Continue to Step 3: Set up your account + +### Step 3: Set up your account + +As a final step to account creation, please tell us about yourself and your experience with Streamlit. This is also when you can read and acknowledge our Terms of use and Privacy notice. The email you provide in this survey is not used as your account email. + +1. Fill in your information and click "**Continue**" at the bottom of the screen. + +
+Fill out the Streamlit Community Cloud user survey +
+ +2. You will be taken to your workspace. + +
+Your Streamlit Community Cloud workspace +
+ +### Finish up + +Congratulations on creating your Streamlit Community Cloud account! A warning icon (warning) next to "**Settings**" in the upper-right corner is expected; this indicates one of three things: + +1. You created a primary identity and skipped connecting GitHub. +2. You started with GitHub and did not create a primary identity. +3. You created both a primary identity and connected GitHub, but the second authorization for GitHub is still pending. You will be prompted with the second authorization when you deploy your first app. + +## What's next? + +Now that you have your account you can [Explore your workspace](/deploy/streamlit-community-cloud/get-started/explore-your-workspace). Or if you're ready to go, jump right in and [Deploy your app](/deploy/streamlit-community-cloud/deploy-your-app). diff --git a/data/deploy/community-cloud/get-started/explore-your-workspace.md b/data/deploy/community-cloud/get-started/explore-your-workspace.md new file mode 100644 index 0000000000000000000000000000000000000000..d3683e3e14df7731f40f5f205d1c06bc0f62449e --- /dev/null +++ b/data/deploy/community-cloud/get-started/explore-your-workspace.md @@ -0,0 +1,40 @@ +--- +title: Explore your workspace +slug: /deploy/streamlit-community-cloud/get-started/explore-your-workspace +--- + +# Explore your workspace + +If you just [created your account](/deploy/streamlit-community-cloud/get-started/create-your-account), congrats! You are now logged in and ready to go. If you are joining someone else's workspace you may already see apps populated in your workspace. If not, then you need to deploy an app! Check out our next section on how to [Deploy your app](/deploy/streamlit-community-cloud/deploy-your-app). If you need an app to deploy, check out our App gallery which includes apps for machine learning, data science, and business use cases. + +![Your Streamlit Community Cloud workspace](/images/streamlit-community-cloud/workspace-empty.png) + +## Switching workspaces + +You may also find that you already have access to multiple Streamlit Community Cloud workspaces. Streamlit Community Cloud automatically groups your apps according to the corresponding GitHub repository's owner or organzation. In the upper-right corner you can see the workspaces you have access to. If apps have already been deployed from any of your repositories, then you will see those apps when you select the associated workspace in the upper-right corner. Learn more about how to [Manage your app from your workspace](/deploy/streamlit-community-cloud/manage-your-app#manage-your-app-from-your-workspace). + +![Switch between your Streamlit Community Cloud workspaces](/images/streamlit-community-cloud/workspace-empty-switch.png) + +## New app button + +Your workspace is your base of operations to deploy apps and manage them. You can click on "**New app**" to [Deploy your app](/deploy/streamlit-community-cloud/deploy-your-app) from a repository where you have administrative privileges. If you want additional options, click the down arrow (expand_more) to begin with a template. + +- "**Use existing repo**" is the default to [Deploy your app](/deploy/streamlit-community-cloud/deploy-your-app) from a repository where you have administrative privileges. +- "**Create from sample app template**" will fork and deploy a simple, one-page Streamlit app. +- "**Create new app with GitHub Codespaces**" will fork and deploy our multipage Streamlit Hello app and create a codespace. To jump quickly into GitHub Codespaces for any of your deployed apps, see [Edit your app with GitHub Codespaces](/deploy/streamlit-community-cloud/manage-your-app/edit-your-app#edit-your-app-with-github-codespaces) instead. + +![Options to deploy a new app from your workspace in Streamlit Community Cloud](/images/streamlit-community-cloud/deploy-menu.png) + +## Invite other developers to your workspace + +Inviting other developers is simple, just invite them to your GitHub repository so that you can code on apps together, and then have them log in to share.streamlit.io/signup. Read more about connecting to a GitHub organization in [Organization access](/deploy/streamlit-community-cloud/get-started/connect-your-github-account#organization-access). + +Streamlit Community Cloud inherits developer permissions from GitHub so when others sign in, they will automatically see the workspaces they share with you. From there you can all deploy, manage, and share apps together. + + + +Once a user is added to a repository on GitHub, it will take at most 15 minutes before they can deploy the app on Cloud. If a user is removed from a repository on GitHub, it will take at most 15 minutes before their permissions to manage the app from that repository are revoked. + + + +And remember, whenever anyone on the team updates the code on GitHub, the app will also automatically update for you! diff --git a/data/deploy/community-cloud/get-started/fork-and-edit.md b/data/deploy/community-cloud/get-started/fork-and-edit.md new file mode 100644 index 0000000000000000000000000000000000000000..39525cc6636fc880cdbbea0086336cb97b363dc7 --- /dev/null +++ b/data/deploy/community-cloud/get-started/fork-and-edit.md @@ -0,0 +1,30 @@ +--- +title: Fork and edit a public app +slug: /deploy/streamlit-community-cloud/get-started/fork-and-edit-a-public-app +--- + +# Fork and edit a public app + +Community Cloud is all about learning, sharing, and exploring the world of Streamlit. For apps with public repositories, you can quickly fork copies to your GitHub account, deploy your own version, and jump into a codespace on GitHub to start editing and exploring Streamlit code — all in the cloud so you don't have to install anything. + +1. From a forkable app, in the upper-right corner, click "fork_right **Fork this app**." + + ![Click Fork this app from a public app](/images/streamlit-community-cloud/fork-and-edit.png) + +2. Click "**Fork!**" The repository will be forked to your GitHub account. If you have already forked the repository or have another repository of the same name, the fork will fail. In this case, you can manually fork the repository on GitHub, then follow the instructions to [Deploy your app](/deploy/streamlit-community-cloud/deploy-your-app#deploy-your-app) and [Edit your app with GitHub Codespaces](/deploy/streamlit-community-cloud/manage-your-app/edit-your-app#edit-your-app-with-github-codespaces). + + ![Click Fork to confirm](/images/streamlit-community-cloud/fork-codespace-1.png) + +3. Click "**Create codespace**" to confirm the creation of a codespace on your account. Read more about GitHub Codespaces to learn about monthly limits for free use and paid plans. + + ![Create a codespace on your GitHub account](/images/streamlit-community-cloud/fork-codespace-2.png) + +4. Wait for GitHub to set up your codespace. + + ![GitHub preparing your codespace](/images/streamlit-community-cloud/deploy-codespaces-3.png) + +5. GitHub will automatically execute the commands to launch your Streamlit app within your codespace. Your app will be visible in a "Simple Browser" on the right. This may take a minute to complete from when your codespace first appears on screen. + + ![Your new GitHub Codespace](/images/streamlit-community-cloud/fork-cheatsheet-codespace.png) + +You now have a copy the public app deployed from your account. You can edit and explore within your codespace and (if you choose) commit your changes to your deployed app to share with the world! 🌎 Learn more about editing your app in GitHub Codespaces, committing your edits to your repository, and shutting down your codespace in [Edit your app with GitHub Codespaces](/deploy/streamlit-community-cloud/manage-your-app/edit-your-app#edit-your-app-with-github-codespaces). diff --git a/data/deploy/community-cloud/get-started/quickstart.md b/data/deploy/community-cloud/get-started/quickstart.md new file mode 100644 index 0000000000000000000000000000000000000000..f5ae885699a87b44a2d19d8f8f06d4cd5fdc26b9 --- /dev/null +++ b/data/deploy/community-cloud/get-started/quickstart.md @@ -0,0 +1,136 @@ +--- +title: Quickstart +slug: /deploy/streamlit-community-cloud/get-started/quickstart +--- + +# Quickstart + +This is a concise set of steps to create your Streamlit Community Cloud account, deploy a sample app, and start editing it with GitHub Codespaces. For other options and complete explanations, start with [Create your account](/deploy/streamlit-community-cloud/get-started/create-your-account). + +You will be signing in to your Google and GitHub accounts during this process. If you do not already have these accounts, you can create them before you begin. If you do not want to use a Google account, you can [create your account with any email](/deploy/streamlit-community-cloud/get-started/create-your-account#primary-identity-option-2-email). + +## Sign up for Streamlit Community Cloud + +1. Go to share.streamlit.io/signup. +2. Click "**Continue with Google**". + +
+Sign up for Streamlit Community Cloud with Google +
+ +3. Enter your Google credentials and follow Google's authentication prompts. +4. After authenticating with Google, click "**Connect GitHub account**". + +
+Connect your GitHub account to Streamlit Community Cloud +
+ +5. Enter your GitHub credentials and follow GitHub's authentication prompts. +6. Click "**Authorize streamlit**". + +
+Authorize streamlit to connect to your GitHub account +
+ +7. To finish, fill in your information and click "**Continue**" at the bottom of the screen. + +
+Set up your Streamlit Community Cloud account +
+ +8. You will be taken to your Streamlit workspace. If you see a warning icon (warning) next to "**Settings**" in the upper-right corner, this will be addressed in the next steps. + +
+Your new workspace in Streamlit Community Cloud +
+ +## Create a new app with GitHub Codespaces + +9. Click the down arrow (expand_more) to expand the options under "**New App**". + +
+Options to deploy a new app from your workspace in Streamlit Community Cloud +
+ +10. Click "**Create new app with GitHub Codespaces**". + +
+Deploy a new app from a sample app template +
+ +11. You will be prompted that "Streamlit is requesting additional permissions". Click "**Authorize streamlit**". + +
+Authorize streamlit to access private repositories +
+ +12. The Streamlit Hello repository will be forked to your GitHub account. Fill in a repository name and click "**Create!**" + +
+Fork the sample Streamlit app +
+ +13. Click "**Create new codespace**" to confirm the creation of a codespace on your GitHub account. Read more about GitHub Codespaces the learn about monthly limits for free use and paid plans. + +
+Create your GitHub Codespace +
+ +14. Wait for GitHub to set up your codespace. + +
+GitHub preparing your Codespace +
+ +15. GitHub will automatically execute the commands to launch your Streamlit app within your codespace. Your app will be visible in a "Simple Browser" on the right. This may take a minute to complete from when your codespace first appears on screen. + +
+Your new GitHub Codespace +
+ +## Edit your app in GitHub Codespaces + +16. Go to the app's main file (`Hello.py`) and add some text to the title in `st.write()`. Try typing ":balloon:" at the beginning. + +
+Edit the title of your sample Streamlit app +
+ +17. Files are automatically saved in your codespace with each edit. Click "**Always rerun**" in the upper-right corner of your app to automatically rerun with each edit. + +
+Select "Always rerun" to automatically see edits in your running app +
+ +18. See your edits and keep going! + +
+See the results of your edit to your Streamlit app +
+ +## Stop or delete your codespace + +When you are done, remember to stop your codespace on GitHub to avoid any undesired use of your capacity. + +19. Go to github.com/codespaces. At the bottom of the page, all your codespaces are listed. Click the overflow menu icon (more_horiz) for your codespace. + +
+Stop or delete your GitHub Codespace +
+ +20. Click "**Stop codespace**" if you'd like to return to your work later. Otherwise, click "**Delete**." + + +
+ Stop your GitHub codespace +
+
+ Delete your GitHub codespace +
+
+ +21. Congratulations! You just deployed an app to Streamlit Community Cloud. 🎉 Head back to your workspace at share.streamlit.io/ and [deploy another Streamlit app](/deploy/streamlit-community-cloud/deploy-your-app). + +
+See your deployed Streamlit app +
diff --git a/data/deploy/community-cloud/get-started/security-model.md b/data/deploy/community-cloud/get-started/security-model.md new file mode 100644 index 0000000000000000000000000000000000000000..de919778e73b8492e0d35b069839072e56a879cb --- /dev/null +++ b/data/deploy/community-cloud/get-started/security-model.md @@ -0,0 +1,72 @@ +--- +title: Streamlit Trust and Security +slug: /deploy/streamlit-community-cloud/get-started/trust-and-security +--- + +# Streamlit trust and security + +Streamlit is a framework that turns Python scripts into interactive apps, giving data scientists the ability to quickly create data and model-based apps for the entire company. + +A simple Streamlit app is: + +```python +import streamlit as st +number = st.slider("Pick a number: ", min_value=1, max_value=10) +st.text("Your number is " + str(number)) +``` + +When you `streamlit run my_app.py`, you start a web server that runs the interactive application on your local computer at `http://localhost:8501`. This is great for local development. When you want to share with your colleagues, Streamlit Community Cloud enables you to deploy and run these applications in the cloud. Streamlit Community Cloud handles the details of containerization and provides you an interface for easily managing your deployed apps. + +This document provides an overview of the security safeguards we've implemented to protect you and your data. Security, however, is a shared responsibility and you are ultimately responsible for making appropriate use of Streamlit and the Streamlit Community Cloud, including implementation of appropriate user-configurable security safeguards and best practices. + +## Product security + +### Authentication + +You must authenticate through GitHub to deploy or administer an app. Authentication through Google or single-use emailed links are required to view a private app when you don't have push or admin permissions on the associated GitHub repository. The single-use emailed links are valid for 15 minutes once requested. + +### Permissions + +Streamlit Community Cloud inherits the permissions you have assigned in GitHub. Users with write access to a GitHub repository for a given app will be able to make changes in the Streamlit administrative console. However, only users with _admin access_ to a repository are able to **deploy and delete apps**. + +## Network and application security + +### Data hosting + +Our physical infrastructure is hosted and managed within secure data centers maintained by infrastructure-as-a-service cloud providers. Streamlit leverages many of these platforms' built-in security, privacy, and redundancy features. Our cloud providers continually monitor their data centers for risk and undergo assessments to ensure compliance with industry standards. + +### Data deletion + +Community Cloud users have the option to delete any apps they’ve deployed as well as their entire account. + +When a user deletes their application from the admin console, we delete their source code, including any files copied from their GitHub repository or created within our system from the running app. However, we keep a record representing the application in our database. This record contains the coordinates of the application: the GitHub organization or user, the GitHub repository, the branch, and the path of the main module file. + +When a user deletes their account, we perform a hard deletion of their data and a hard deletion of all the apps that belong to the GitHub identity associated with their account. In this case, we do not maintain the records of application coordinates described above. When an account is deleted, we also delete any HubSpot contact associated with the Community Cloud account. + +### Virtual private cloud + +All of our servers are within a virtual private cloud (VPC) with firewalls and network access control lists (ACLs) to allow external access to a select few API endpoints; all other internal services are only accessible within the VPC. + +### Encryption + +Streamlit apps are served entirely over HTTPS. We use only strong cipher suites and HTTP Strict Transport Security (HSTS) to ensure browsers interact with Streamlit apps over HTTPS. + +All data sent to or from Streamlit over the public internet is encrypted in transit using 256-bit encryption. Our API and application endpoints use Transport Layer Security (TLS) 1.2 (or better). We also encrypt data at rest on disk using AES-256. + +### Permissions and authentication + +Access to Community Cloud user account data is limited to authorized personnel. We run a zero-trust corporate network, utilize single sign-on and multi-factor authentication (MFA), and enforce strong password policies to ensure access to cloud-related services is protected. + +### Incident response + +Our internal protocol for handling security events includes detection, analysis, response, escalation, and mitigation. Security advisories are made available at [https://streamlit.io/advisories](https://streamlit.io/advisories). + +### Penetration testing + +Streamlit uses third-party security tools to scan for vulnerabilities on a regular basis. Our security teams conduct periodic, intensive penetration tests on the Streamlit platform. Our product development team responds to any identified issues or potential vulnerabilities to ensure the quality, security, and availability of Streamlit applications. + +### Vulnerability management + +We keep our systems up-to-date with the latest security patches and continuously monitor for new vulnerabilities. This includes automated scanning of our code repositories for vulnerable dependencies. + +If you discover a vulnerability in one of our products or websites, please report the issue to [HackerOne](https://hackerone.com/snowflake?type=team). diff --git a/data/deploy/community-cloud/manage-your-account/_index.md b/data/deploy/community-cloud/manage-your-account/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..65c36626cabca2058abe283424a9701b362fe9e0 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-account/_index.md @@ -0,0 +1,20 @@ +--- +title: Manage your account +slug: /deploy/streamlit-community-cloud/manage-your-account +--- + +# Manage your account + +You can [Update your email](/deploy/streamlit-community-cloud/manage-your-account/update-your-email) or [Delete your account](/deploy/streamlit-community-cloud/manage-your-account/delete-your-account) entirely through [Workspace settings](/deploy/streamlit-community-cloud/manage-your-account/workspace-settings). + +When using Streamlit Community Cloud, you have two identities behind your account: a primary identity (Google or email) and source control (GitHub). Your primary identity allows other users to share private apps with you and grant you access to their analytics. Your source control identity allows you to deploy apps from GitHub repositories and manage them through your Streamlit Community Cloud workspace. + +## Access your workspace settings + +To manage your account, sign in to share.streamlit.io and click "**Settings**" in the top right corner to access your workspace settings. + +
+ Access your workspace settings from your workspace +
+ +Learn more about how to [Update your email](/deploy/streamlit-community-cloud/manage-your-account/update-your-email) and [Delete your account](/deploy/streamlit-community-cloud/manage-your-account/delete-your-account). diff --git a/data/deploy/community-cloud/manage-your-account/delete-your-account.md b/data/deploy/community-cloud/manage-your-account/delete-your-account.md new file mode 100644 index 0000000000000000000000000000000000000000..1f9685b5b43955ebbe28b18d96069dd55de87f88 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-account/delete-your-account.md @@ -0,0 +1,37 @@ +--- +title: Delete your account +slug: /deploy/streamlit-community-cloud/manage-your-account/delete-your-account +--- + +# Delete your account + +Deleting your Streamlit Community Cloud account is just as easy as creating it. When you delete your account, your information, account, and all your hosted apps are deleted as well. Read more about data deletion in [Streamlit trust and security](/deploy/streamlit-community-cloud/get-started/trust-and-security#data-deletion). + + + +Deleting your account is permanent and cannot be undone. Make sure you really want to delete your account and all hosted apps before proceeding. Any app you've deployed will be deleted, regardless of the workspace it was deployed from. + + + +## How to delete your account + +Follow these steps to delete your account: + +1. Sign in to Streamlit Community Cloud at share.streamlit.io and access your [Workspace settings](/deploy/streamlit-community-cloud/manage-your-account/workspace-settings). + +2. From the "Linked accounts" section, click "**Delete account**". + +
+ Delete your Streamlit Community Cloud account from your workspace settings +
+ +3. A confirmation will display. Enter the confirmation string and click "**Delete account forever**" + +
+ Confirm your account deletion by typing the specified string +
+ +4. All your information and apps will be permanently deleted. + ![Your Streamlit Community Cloud account has been deleted.](/images/streamlit-community-cloud/account-deleted.png) + +It's that simple! If you have any questions or run into issues deleting your account, please reach out to us on our forum. We're happy to help! 🎈 diff --git a/data/deploy/community-cloud/manage-your-account/manage-your-github-connection.md b/data/deploy/community-cloud/manage-your-account/manage-your-github-connection.md new file mode 100644 index 0000000000000000000000000000000000000000..70de87f1281cbe26cd0e36ec66c69d21d40da65e --- /dev/null +++ b/data/deploy/community-cloud/manage-your-account/manage-your-github-connection.md @@ -0,0 +1,95 @@ +--- +title: Manage your GitHub connection +slug: /deploy/streamlit-community-cloud/manage-your-account/manage-your-github-connection +--- + +# Manage your GitHub connection + +If you did not connect GitHub when you created your account or need to correct your GitHub authorization, this page is for you! If you just need to add an organization to your account, skip ahead to [Authorizing with an organization](#authorizing-with-an-organization). + +If you are not fully logged in and authorized to both a primary identity (Google or email) and source control (GitHub), there will be a warning symbol in the upper-right corner of your workspace. This can mean one of three things: + +- You are not signed in to a primary identity (Google or email). + - See [Connect Google to your account](/deploy/streamlit-community-cloud/manage-your-account/update-your-email#connect-google-to-your-account). +- You are not signed in to source control (GitHub.) + - See [Connecting GitHub to an existing primary identity](#connecting-github-to-an-existing-primary-identity). +- Your source control has incomplete permissions. + - Access your workspace settings see [Authorize Streamlit to access private repositories](#authorize-streamlit-to-access-private-repositories). + +Authorize your GitHub account + +## Connecting GitHub to an existing primary identity + +If you created your account without connecting GitHub or if you disconnected GitHub from your account, you can reconnect. + +1. Click "**Settings**" in the upper-right corner of your workspace. +2. If you do not have GitHub connected, a warning is displayed saying, "**You are not signed in with a source control account**". + +If instead you see "**Streamlit does not have access to private repos on this GitHub account**" skip to step 5. 3. Click "**Sign in with GitHub**". + +
+Sign in with GitHub to connect GitHub to your Streamlit Community Cloud account +
+ +4. Click "**Authorize streamlit**". + +
+Authorize streamlit to connect to your GitHub account +
+ +### Authorize Streamlit to access private repositories + +5. After completing the first authorization, your workspace settings will still have a warning, "**Streamlit does not have access to private repos on this GitHub account**". + +6. Click "**Allow access**". + +
+Click 'Allow access' to trigger the second GitHub authorization +
+ +7. Click "**Authorize streamlit**". + +
+Authorize streamlit to access private repositories +
+ +GitHub is now connected to your account! 🥳 + +## Authorizing with an organization + +If you are in an organization, you can grant or request access to that organization when you connect your GitHub account. Read more about [Organization access](/deploy/streamlit-community-cloud/get-started/connect-your-github-account#organization-access). + +If your GitHub account is already connected, you can remove permissions in your GitHub settings and force Streamlit to reprompt for GitHub authorization the next time you sign into Streamlit Community Cloud. + +### Revoke and reauthorize + +1. From your workspace, click on your workspace name in the upper-right corner. Click "**Sign out**" to sign out of Streamlit Community Cloud. + +
+Sign out of Streamlit Community Cloud +
+ +2. Go to your GitHub application settings at github.com/settings/applications. +3. Click on the three dots to open the overflow menu for "**Streamlit**" and click "**Revoke**". + +
+Revoke access for Streamlit to access your GitHub account +
+ +4. Click "**I understand, revoke access**". + +
+Confirm to revoke access for Streamlit to your GitHub account +
+ +5. Return to share.streamlit.io and sign in. You will be prompted to authorize GitHub as explained in [Connect GitHub](/deploy/streamlit-community-cloud/get-started/connect-your-github-account#organization-access). + +### Granting previously denied access + +If an organization owner has restricted Streamlit's access or restricted all OAuth applications, they may need to directly modify their permissions in GitHub. If an organization has restricted Streamlit's access, a red "**X**" will appear next to the organization when you are prompted to authorize with your GitHub account. + +
+Denied authorization for Streamlit to access your GitHub account +
+ +See GitHub's documentation on OAuth apps and organizations. diff --git a/data/deploy/community-cloud/manage-your-account/sign-in-sign-out.md b/data/deploy/community-cloud/manage-your-account/sign-in-sign-out.md new file mode 100644 index 0000000000000000000000000000000000000000..3eeb9b8463eb632ab7a3ce3904d23f69cb3cd6b4 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-account/sign-in-sign-out.md @@ -0,0 +1,72 @@ +--- +title: Sign in & sign out +slug: /deploy/streamlit-community-cloud/manage-your-account/sign-in-sign-out +--- + +# Sign in & sign out + +Once you've created your account, you can sign in to share.streamlit.io and follow the steps below. + +![Sign in to Streamlit Community Cloud](/images/streamlit-community-cloud/sign-in.png) + +## Sign in with Google + +1. Visit share.streamlit.io and click "**Continue with Google**". + +
+ Sign in to Streamlit Community Cloud with Google +
+ +2. Enter your Google account credentials. + +
+ Enter your Google credentials to sign in to Streamlit Community Cloud +
+ +3. If your account is already linked to GitHub, you may be immediately prompted to sign in with GitHub. Once you have signed in, you can [Explore your workspace!](/deploy/streamlit-community-cloud/get-started/explore-your-workspace). 🎈 + +## Sign in with GitHub + +1. Visit share.streamlit.io and click "**Continue with GitHub**". + +
+ GitHub sign-in +
+ +2. Enter your GitHub credentials. + +
+ GitHub sign-in +
+ +3. Once you have signed in to GitHub, you can [Explore your workspace!](/deploy/streamlit-community-cloud/get-started/explore-your-workspace). 🎈 + +## Sign in with Email + +1. Visit share.streamlit.io and enter the email you used to create your Streamlit Community Cloud account. Click "**Continue with email**". + +
+ Email sign-in +
+ +2. You will see a confirmation message asking you to check your email. + +
+ Email sign-in +
+ +3. Check your inbox for an email with the subject "**Sign in to Streamlit Cloud**". Click the link in the email to sign in to Streamlit Community Cloud. Note that this link will expire in 15 minutes and can only be used once. + +
+ Email sign-in +
+ +4. Once you click the link in your email, you can [Explore your workspace!](/deploy/streamlit-community-cloud/get-started/explore-your-workspace). 🎈 + +## Sign out of your account + +From your workspace, click on your workspace name in the upper-right corner. Click "**Sign out**". + +
+Sign out of Streamlit Community Cloud +
diff --git a/data/deploy/community-cloud/manage-your-account/update-your-email.md b/data/deploy/community-cloud/manage-your-account/update-your-email.md new file mode 100644 index 0000000000000000000000000000000000000000..eae523bff8d468764baab27815006bf1d17fccf4 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-account/update-your-email.md @@ -0,0 +1,76 @@ +--- +title: Update your email +slug: /deploy/streamlit-community-cloud/manage-your-account/update-your-email +--- + +# Update your email + +If you wish to update your email on Streamlit Community Cloud, you can do so via your [Workspace settings](/deploy/streamlit-community-cloud/manage-your-account/workspace-settings). Updating your email changes the primary identity of your account. Once updated, if your account's email is associated with a Google account, you can sign in with Google OAuth. Otherwise, you through emailed links. The latter involves typing in your email, after which we'll send you a unique, single-use link (valid for 15 minutes). + +If you are signed in to GitHub and don't already have a primary identity on your account, see [Connect Google to your account](#connect-google-to-your-account). + +## How to update your email + +1. Sign in to Streamlit Community Cloud at share.streamlit.io. +2. Click "**Settings**" in the page's top-right corner. + ![Access your workspace settings from your workspace](/images/streamlit-community-cloud/account-settings-header.png) + +3. Click "**Update email**" within the "**Linked accounts**" section. + ![Update your email from your workspace settings](/images/streamlit-community-cloud/account-change-email-1.png) + +4. Enter your new email and click "**Update email**." + ![Enter your new email address for your Streamlit Community Cloud account](/images/streamlit-community-cloud/account-change-email-2.png) + +5. You'll see a confirmation dialog asking you to check your email for a confirmation link. Click "**Done**." + ![Confirmation message after choosing a new email for your Streamlit Community Cloud account](/images/streamlit-community-cloud/account-change-email-3.png) + +6. Your account settings will show "**Update pending**" until you complete the next step. + ![Email update pending displayed in your workspace settings](/images/streamlit-community-cloud/account-change-email-4.png) + +7. Check your inbox for an email from Streamlit containing a "**Change email**" button and a confirmation link. This one-time link expires in 15 minutes. Click either one to confirm your new email address for Streamlit Community Cloud. Before doing so, ensure you access the link from the same browser session where you are logged in to Streamlit Community Cloud. + + + + If you access the confirmation link from a browser session where you are not logged in to Streamlit Community Cloud, the confirmation link will not complete the process. You will be prompted to sign in. If you try to sign in with your new email, you will create a second account instead. See [Troubleshooting](#troubleshooting). + + + + ![Click 'Change email' from the message sent to your email account](/images/streamlit-community-cloud/account-change-email-5.png) + +8. A confirmation will display to confirm your email update is complete! 🎈 + ![Confirmation that your email has been changed on your Streamlit Community Cloud account](/images/streamlit-community-cloud/account-change-email-6.png) + +## Resend your confirmation link + +If your confirmation link expires, don't worry! You can resend it by following these steps: + +1. Sign in to Streamlit Community Cloud at share.streamlit.io and click "**Settings**" in the page's top-right corner. +2. Click "**Update pending**" + ![Click 'Update pending' from your workspace settings](/images/streamlit-community-cloud/account-change-email-7.png) + +3. Click "**Resend email**" + ![Click 'Resend email' to resend the confirmation link to your email](/images/streamlit-community-cloud/account-change-email-8.png) + +4. Continue from step 4 of [How to update your email](#how-to-update-your-email). + +## Troubleshooting + +If you click the confirmation link in a browser session where you are not signed in, you will be informed that "Sign in is required." If you try to sign in with your new email, you will create a second account instead. You cannot resend your confirmation link while you have this second account. If you accidentally created a second account, you can follow the steps to [Delete your account](/deploy/streamlit-community-cloud/manage-your-account/delete-your-account) to get rid of the duplicate. Afterwards, [Resend your confirmation link](#resend-your-confirmation-link) from your first account. + +## Connect Google to your account + +1. If you signed up with GitHub and did not create a primary identity, your workspace will show a warning icon in the upper right corner. Click "**Settings**" to access your workspace settings. + + ![Your workspace without a primary identity](/images/streamlit-community-cloud/account-settings-header-warning.png) + +2. When you access your workspace settings, a warning is displayed: "You are not signed in with a primary identity account." Click "**Sign in with Google**" and follow Google's authentication prompts. + +
+ Sign in with Google to connect your email to your Streamlit Community Cloud account +
+ +3. Your account now has both a primary identity and source control account. + +
+ A fully signed-in Streamlit Community Cloud account +
diff --git a/data/deploy/community-cloud/manage-your-account/workspace-settings.md b/data/deploy/community-cloud/manage-your-account/workspace-settings.md new file mode 100644 index 0000000000000000000000000000000000000000..750b20be0cb08e33dc555317cd3ed4c8329e191d --- /dev/null +++ b/data/deploy/community-cloud/manage-your-account/workspace-settings.md @@ -0,0 +1,32 @@ +--- +title: Workspace settings +slug: /deploy/streamlit-community-cloud/manage-your-account/workspace-settings +--- + +# Workspace settings + +From your workspace settings you can [Manage your account](/deploy/streamlit-community-cloud/manage-your-account), see your [App resources and limits](/deploy/streamlit-community-cloud/manage-your-app#app-resources-and-limits) and access support resources. + +## Access your workspace settings + +From your workspace at share.streamlit.io, click "**Settings**" in the upper-right corner. + +![Access your workspace settings](/images/streamlit-community-cloud/account-settings-header.png) + +## Linked accounts + +The "**Linked accounts**" section shows your current primary identity and source control account. To learn more, see [Manage your account](/deploy/streamlit-community-cloud/manage-your-account). + +![Manage your linked accounts in workspace settings](/images/streamlit-community-cloud/account-primary-identity-and-source-control.png) + +## Limits + +The "**Limits**" section shows your current resources and limits. To learn more, see [App resources and limits](/deploy/streamlit-community-cloud/manage-your-app#app-resources-and-limits). + +![Resource limits displayed in workspace settings](/images/streamlit-community-cloud/workspace-limits.png) + +## Support + +The "**Support**" section provides a convenient list of useful resources so you know where to go for help. + +![Support options available through workspace settings](/images/streamlit-community-cloud/workspace-support.png) diff --git a/data/deploy/community-cloud/manage-your-app/_index.md b/data/deploy/community-cloud/manage-your-app/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..09a69a49e60b6fbca7177de04b39770274428823 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-app/_index.md @@ -0,0 +1,157 @@ +--- +title: Manage your app +slug: /deploy/streamlit-community-cloud/manage-your-app +--- + +# Manage your app + +You can manage your deployed app from your workspace at share.streamlit.io or directly from `.streamlit.app`. You can view, deploy, delete, reboot, or favorite an app. + +## Manage your app from your workspace + +Streamlit Community Cloud is organized into workspaces, which automatically group your apps according to the corresponding GitHub repository's owner. Your workspace is indicated in the upper-right corner. You will have one workspace that matches your GitHub username and additional workspaces for any GitHub organization or user who has granted you access. + +Additionally, if you have view-only access to an app, you will be able to see that app's workspace. When you do not have developer access to an app, your management options for that app will be restricted as shown in the following sections. + +To deploy or manage any app, always switch to the workspace matching the repository's owner first. + +![Switching between app workspaces in Streamlit Community Cloud](/images/streamlit-community-cloud/workspace-switch.png) + +At the top of your workspace, "**Analytics**" is a shortcut to [App analytics](/deploy/streamlit-community-cloud/manage-your-app/app-analytics) and "**Settings**" links to your [Workspace settings](/deploy/streamlit-community-cloud/manage-your-account/workspace-settings) (not to be confused with [App settings](/deploy/streamlit-community-cloud/manage-your-app/app-settings) for each of your apps). + +### App overflow menus + +Each app has a menu accessible from the overflow icon (more_vert) to the right. + +- **Copy URL** — See [Copy your app's URL](/deploy/streamlit-community-cloud/share-your-app#copy-your-apps-url) +- **Edit** — See [Edit your app with GitHub Codespaces](/deploy/streamlit-community-cloud/manage-your-app/edit-your-app#edit-your-app-with-github-codespaces) +- **Favorite** — See [Favorite your app](/deploy/streamlit-community-cloud/manage-your-app/favorite-your-app) +- **Analytics** — See [App analytics](/deploy/streamlit-community-cloud/manage-your-app/app-analytics) +- **Reboot** — See [Reboot your app](/deploy/streamlit-community-cloud/manage-your-app/reboot-your-app) +- **Delete** — See [Delete your app](/deploy/streamlit-community-cloud/manage-your-app/delete-your-app) +- **Settings** — See [App settings](/deploy/streamlit-community-cloud/manage-your-app/app-settings) + +![App overflow menu in your workspace](/images/streamlit-community-cloud/workspace-app-overflow.png) + +If you have view-only access to an app, options will be restricted in that app's menu. + +![View-only app overflow menu in your workspace](/images/streamlit-community-cloud/workspace-view-only.png) + +## Manage your app directly from your app + +You can manage your deployed app directly from the app itself! Just make sure you are signed in to Streamlit Community Cloud then visit your app. + +### Streamlit Community Cloud logs + +1. From your app at `.streamlit.app`, click "**Manage app**" in the lower-right corner. + + ![Access Cloud logs from Manage app in the lower-right corner of your app](/images/streamlit-community-cloud/cloud-logs-open.png) + +2. Once you've clicked on "**Manage app**", you will be able to view your app's logs. This is your primary place to troubleshoot any issues with your app. + + ![Streamlit Community Cloud logs](/images/streamlit-community-cloud/cloud-logs.png) + +3. You can access more developer options by clicking the overflow icon (more_vert) at the bottom of your Cloud logs. To conveniently download your logs, click "**Download log**". + + ![Download your Streamlit Community Cloud logs](/images/streamlit-community-cloud/cloud-logs-menu-download.png) + + + +
+ +Other options accessible from Cloud logs are: + +- **Analytics** — See [App analytics](/deploy/streamlit-community-cloud/manage-your-app/app-analytics). +- **Reboot app** — See [Reboot your app](/deploy/streamlit-community-cloud/manage-your-app/reboot-your-app). +- **Delete app** — See [Delete your app](/deploy/streamlit-community-cloud/manage-your-app/delete-your-app). +- **Settings** — See [App settings](/deploy/streamlit-community-cloud/manage-your-app/app-settings). +- **Your apps** — Takes you to your [app workspace](#manage-your-app-from-your-workspace). +- **Documentation** — Takes you to our documentation. +- **Support** — Takes you to our forums! + +
+ +
+ +
+ +
+ +### App menus + +From your app at `.streamlit.app`, you can always access your [app's menu](/develop/concepts/architecture/app-chrome) just like you can when developing locally. The option to deploy your app is removed, but you can still clear your cache from here. + +![App menus in Streamlit Community Cloud](/images/streamlit-community-cloud/app-menu.png) + +## Manage your app in GitHub + +### Update your app + +Your GitHub repository is the source for the app, so that means that any time you push an update to your repo you'll see it reflected in the app in almost real time. Try it out! + +Streamlit also smartly detects whether you touched your dependencies, in which case it will automatically do a full redeploy for you—which will take a little more time. But since most updates don't involve dependency changes, you should usually see your app update in real time. + +### Add or remove dependencies + +You can add/remove dependencies at any point by updating `requirements.txt` (Python dependenciess) or `packages.txt` (Linux dependencies) and committing the changes to your repository on GitHub. This will cause Streamlit Community Cloud to detect there was a change in your dependencies and automatically trigger (re)installation. + +It is best practice to pin your Streamlit version in `requirements.txt`. Otherwise, the version may be auto-upgraded at any point without your knowledge, which could lead to undesired results (e.g. when we deprecate a feature in Streamlit). + +## App resources and limits + +### Resource limits + +All Streamlit Community Cloud users have access to the same resources and are subject to the same limits. These limits may change at any time without notice. If your app meets or exceeds its limits, it may slow down from throttling or become nonfunctional. The limits as of February 2024 are approximately as follows: + +- CPU: 0.078 cores minimum, 2 cores maximum +- Memory: 690MB minimum, 2.7GBs maximum +- Storage: No minimum, 50GB maximum + +Symptoms that your app is running out of resources include the following: + +- Your app is running slowly. +- Your app displays "🤯 This app has gone over its resource limits." +- Your app displays "😦 Oh no." + +### Good for the world + +Streamlit offers increased resources for apps with good-for-the-world use cases. Generally, these apps are used by an educational institution or nonprofit organization, are part of an open-source project, or benefit the world in some way. If your app is **not** primarily used by a for-profit company you can [apply for increased resources](https://share.hsforms.com/1DzDGAjUmSPy_2nUzBj3rlQ3wudj). + +If you are an educator or student looking to deploy additional private apps, please [apply to our education program](https://share.hsforms.com/1M_e2WDcSRFuKzA2iteoAIg3wudj) instead. + +### Optimizing your app + +If your app is running slow or showing the error pages mentioned above, we first highly recommend going through and implementing the suggestions in the following blog posts to prevent your app from hitting the resource limits and to detect if your Streamlit app leaks memory: + +- Common app problems: Resource limits +- 3 steps to fix app memory leaks + +If your app exceeds its resource limits, developers and viewers alike will see "😦 Oh no." + +
+App state: Oh no. Error running your app. +
+ +If see "😦 Oh no." when viewing your app, first check your Cloud logs for any specific errors. If there are no errors in your Cloud logs you are likely dealing with a resource issue. + +#### Developer view + +If you are logged into a developer account for an app over its limits, you can access "**Manage app**" from the lower-right corner of the app to reboot it and clear its memory. "**Manage app**" will be red and have a warning icon (error). + +![Developer view: Oh no. Error running your app.](/images/streamlit-community-cloud/app-state-oh-no-developer.png) + +### App hibernation + +All apps without traffic for 7 consecutive days will automatically go to sleep. This is done to alleviate resources and allow the best communal use of the platform! If you would like to keep your app awake, simply visit the app to create traffic or commit your app's repository, even if it's an empty commit! + +If left alone your app will go to sleep at the 7 day mark. When someone visits the app after this, they will see the sleeping page: + +
+App state: Zzzz. This app has gone to sleep due to inactivity. +
+ +To wake the app up, click "**Yes, get this app back up!**" This can be done by *anyone* who has access to view the app, not just the app developer! + +You can see which of your apps are asleep from your workspace. Sleeping apps have a moon icon (bedtime) to the right. + +![App state: Zzzz. This app has gone to sleep due to inactivity](/images/streamlit-community-cloud/app-state-zzzz-workspace.png) diff --git a/data/deploy/community-cloud/manage-your-app/app-analytics.md b/data/deploy/community-cloud/manage-your-app/app-analytics.md new file mode 100644 index 0000000000000000000000000000000000000000..60709b2f7cce74c6b0f2d79f3671eef9d61ac9b1 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-app/app-analytics.md @@ -0,0 +1,69 @@ +--- +title: App analytics +slug: /deploy/streamlit-community-cloud/manage-your-app/app-analytics +--- + +# App analytics + +Streamlit Community Cloud allows you to see the viewership of each of your apps. Specifically, you can see: + +- The total viewers count of your app (counted from April 2022). +- The most recent unique viewers (capped up to your last 20 viewers). +- A relative timestamp of each unique viewer's last visit. + +![App analytics on Streamlit Community Cloud](/images/streamlit-community-cloud/workspace-app-analytics-viewers.png) + +## Access your app analytics + +You can get to your app's analytics: + +- [From your workspace](#access-app-analytics-from-your-workspace). +- [From your Cloud logs](#access-app-analytics-from-your-cloud-logs). + +### Access app analytics from your workspace + +From your workspace at share.streamlit.io, click the overflow icon (more_vert) next to your app. Click "**Analytics**". + +![Access app analytics from your workspace through your app overflow menu](/images/streamlit-community-cloud/workspace-app-analytics.png) + +Alternatively, from the top of your workspace, click "**Analytics**". + +![Access app analytics from your workspace](/images/streamlit-community-cloud/workspace-analytics.png) + +### Access app analytics from your Cloud logs + +From your app at `.streamlit.app`, click "**Manage app**" in the lower-right corner. + +![Access Streamlit Community Cloud logs from your app](/images/streamlit-community-cloud/cloud-logs-open.png) + +Click the overflow menu icon (more_vert) and click "**Analytics**". + +![Access app analytics from your Cloud logs](/images/streamlit-community-cloud/cloud-logs-menu-analytics.png) + +## Switch between apps + +Once you are in the analytics modal, you can switch between apps in your workspace from the drop-down list. Remember to switch workspaces if you want to view analytics for an app in another workspace. + +![Switch between apps with app analytics](/images/streamlit-community-cloud/workspace-app-analytics-switch.png) + +## App viewers + +For public apps, we anonymize all viewers outside your workspace to protect their privacy and display anonymous viewers as random pseudonyms. You'll still be able to see the identities of fellow members in your workspace, including any viewers you've invited (once they've accepted). + + + +When you invite a viewer to an app, they gain access to analytics as well. Additionally, if someone is invited as a viewer to _any_ app in your workspace, they can see analytics for all public apps in your workspace and invite additional viewers themselves. A viewer in your workspace may see the emails of developers and other viewers in your workspace through analytics. + + + +Meanwhile, for private apps where you control who has access, you will be able to see the specific users who recently viewed your apps. + +Additionally, you may occasionally see anonymous users in a private app. Rest assured, these anonymous users _do_ have authorized view access granted by you or your workspace members. + +Common reasons why users show up anonymously are: + +1. The app was previously public. +2. The given viewer viewed the app in April 2022, when the Streamlit team was honing user identification for this feature. +3. The given viewer previously disconnected their primary identity (Google or email) and source control identity (GitHub). + +See Streamlit's general Privacy Notice. diff --git a/data/deploy/community-cloud/manage-your-app/app-settings.md b/data/deploy/community-cloud/manage-your-app/app-settings.md new file mode 100644 index 0000000000000000000000000000000000000000..3095ff09f0a18e9e72b96f8dca5c6ea242a5d100 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-app/app-settings.md @@ -0,0 +1,53 @@ +--- +title: App settings +slug: /deploy/streamlit-community-cloud/manage-your-app/app-settings +--- + +# App settings + +This page is about your app settings on Streamlit Community Cloud. From your app settings you can [view or modify your app's URL](/deploy/streamlit-community-cloud/deploy-your-app#custom-subdomains), [manage public or private access to your apps](/deploy/streamlit-community-cloud/share-your-app) and [update your saved secrets for your apps](/deploy/streamlit-community-cloud/deploy-your-app/secrets-management). + +If you access "**Settings**" from your [App menu](/develop/concepts/architecture/app-chrome) in the upper-right corner of your running app, you can access features to control the appearance of your app while its running. + +## Access your app settings + +You can get to your app's settings: + +- [From your workspace](#access-app-settings-from-your-workspace). +- [From your Cloud logs](#access-app-settings-from-your-cloud-logs). + +### Access app settings from your workspace + +From your workspace at share.streamlit.io, click the overflow icon (more_vert) next to your app. Click "**Settings**". + +![Access app settings from your workspace](/images/streamlit-community-cloud/workspace-app-settings.png) + +### Access app settings from your Cloud logs + +From your app at `.streamlit.app`, click "**Manage app**" in the lower-right corner. + +![Access Streamlit Community Cloud logs from your app](/images/streamlit-community-cloud/cloud-logs-open.png) + +Click the overflow menu icon (more_vert) and click "**Settings**". + +![Access app settings from your Cloud logs](/images/streamlit-community-cloud/cloud-logs-menu-settings.png) + +## Change your app settings + +### View or change your app's URL + +Read more about [Custom subdomains](/deploy/streamlit-community-cloud/deploy-your-app#custom-subdomains). + +![General app settings on Streamlit Community Cloud: Custom subdomain](/images/streamlit-community-cloud/workspace-app-settings-general.png) + +### Update your app's share settings + +Learn how to [Share your app](/deploy/streamlit-community-cloud/share-your-app). + +![Share settings on Streamlit Community Cloud](/images/streamlit-community-cloud/workspace-app-settings-sharing.png) + +### Update your secrets + +Learn more about [Secrets management](/deploy/streamlit-community-cloud/deploy-your-app/secrets-management). + +![Secrets settings on Streamlit Community Cloud](/images/streamlit-community-cloud/workspace-app-settings-secrets.png) diff --git a/data/deploy/community-cloud/manage-your-app/delete-your-app.md b/data/deploy/community-cloud/manage-your-app/delete-your-app.md new file mode 100644 index 0000000000000000000000000000000000000000..2a7d96a9ba5fe61a5f40ebdb29c64e4a161d375f --- /dev/null +++ b/data/deploy/community-cloud/manage-your-app/delete-your-app.md @@ -0,0 +1,47 @@ +--- +title: Delete your app +slug: /deploy/streamlit-community-cloud/manage-your-app/delete-your-app +--- + +# Delete your app + +If you need to delete your app, it's simple and easy. There are several cases where you may need to delete your app: + +- You have finished playing around with an example app. +- You want to deploy from a private repository but already have a private app. +- You want to change the Python version for your app or otherwise redeploy your app. + +If you delete your app and intend to immediately redploy it, your custom subdomain should be immediately available for reuse. Read more about data deletion in [Streamlit trust and security](/deploy/streamlit-community-cloud/get-started/trust-and-security#data-deletion). + +You can delete your app: + +- [From your workspace](#delete-your-app-from-your-workspace). +- [From your Cloud logs](#delete-your-app-from-your-cloud-logs). + +### Delete your app from your workspace + +1. From your workspace at share.streamlit.io, click the overflow icon (more_vert) next to your app. Click "**Delete**". + + ![Delete your app from your workspace](/images/streamlit-community-cloud/workspace-app-delete.png) + +2. A confirmation will display. Enter the required confirmation string and click "**Delete**". + +
+Confirm deleting your app from Streamlit Community Cloud +
+ +### Delete your app from your Cloud logs + +1. From your app at `.streamlit.app`, click "**Manage app**" in the lower-right corner. + + ![Access Streamlit Community Cloud logs from your app](/images/streamlit-community-cloud/cloud-logs-open.png) + +2. Click the overflow menu icon (more_vert) and click "**Delete app**". + + ![Delete your app from your Cloud logs](/images/streamlit-community-cloud/cloud-logs-menu-delete.png) + +3. A confirmation will display. Enter the required confirmation string and click "**Delete**". + +
+Confirm deleting your app from Streamlit Community Cloud +
diff --git a/data/deploy/community-cloud/manage-your-app/edit-your-app.md b/data/deploy/community-cloud/manage-your-app/edit-your-app.md new file mode 100644 index 0000000000000000000000000000000000000000..f99bcc9bbc89f8cee3c4e4e8da9c4581d4466221 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-app/edit-your-app.md @@ -0,0 +1,86 @@ +--- +title: Edit your app +slug: /deploy/streamlit-community-cloud/manage-your-app/edit-your-app +--- + +# Edit your app + +You can edit your app from any development environment of your choice. Community Cloud will monitor your repository and automatically copy any file changes you commit. You will immediately see commits reflected in your deployed app for most changes (such as edits to your app's Python files). + +Community Cloud also makes it easy to skip the work of setting up a development environment. With a few simple clicks, you can configure a development environment using GitHub Codespaces. + +## Edit your app with GitHub Codespaces + +Spin up a cloud-based development environment for your deployed app in minutes. You can run your app within your codespace to enjoy experimenting in a safe, sandboxed environment. When you are done editing your code, you can commit your changes to your repo or just leave them in your codespace to return to later. + +### Create a codespace for your deployed app + +1. From your workspace at share.streamlit.io, click the overflow icon (more_vert) next to your app. Click "**Edit**." + + ![Edit your app with GitHub Codespaces](/images/streamlit-community-cloud/workspace-app-edit.png) + +2. A `.devcontainer/devcontainer.json` file will be added to your repository. If you already have a file of the same name in your repository, it will not be changed. You may delete or rename your existing devcontainer configuration if you would like your repository to receive the instance created by Streamlit Community Cloud. + + ![Adding a devcontainer file to your repository](/images/streamlit-community-cloud/workspace-app-edit-preparing.png) + +3. Click "**Create codespace**" to confirm the creation of a codespace on your account. Read more about GitHub Codespaces to learn about monthly limits for free use and paid plans. + + ![Create your GitHub Codespace](/images/streamlit-community-cloud/deploy-codespaces-2.png) + +4. Wait for GitHub to set up your codespace. + + ![GitHub preparing your codespace](/images/streamlit-community-cloud/deploy-codespaces-3.png) + +5. GitHub will automatically execute the commands to launch your Streamlit app within your codespace. Your app will be visible in a "Simple Browser" on the right. This may take a minute to complete from when your codespace first appears on screen. + + ![Your new GitHub Codespace](/images/streamlit-community-cloud/deploy-sample-codespace.png) + +6. When you make changes to your app, the file is automatically saved within your codespace. Your edits do not affect your repository unless you choose to commit those changes. We will describe committing your changes in a later step. + + In order to see updates automatically reflected on the right, click "**Always rerun**" when prompted after an edit. + + ![Edit the title of your sample Streamlit app](/images/streamlit-community-cloud/deploy-sample-edit-title.png) + ![Select "Always rerun" to automatically see edits in your running app](/images/streamlit-community-cloud/deploy-sample-edit-rerun.png) + +7. See your edits appear within the "Simple Browser" tab and keep going with more! + + ![See the results of your edit to your Streamlit app](/images/streamlit-community-cloud/deploy-sample-edit-result.png) + +### Commit your changes to your repository (optional) + +After making edits to your app, you can choose to commit your edits to your repository to update your deployed app instantly. If you just want to keep your edits in your codespace to return to later, skip to [Stop or delete your codespace](#stop-or-delete-your-codespace). + +8. In the left navigation bar, click the source control icon. + + ![Click on the source control icon](/images/streamlit-community-cloud/deploy-sample-edit-commit-1.png) + +9. Fill out your desired commit message and click "**Commit**." + + ![Commit your changes](/images/streamlit-community-cloud/deploy-sample-edit-commit-2.png) + +10. Click "**Yes**" to stage and commit all your changes. To learn more about source control in GitHub Codespaces, check out Source control in GitHub Docs. + +
+Confirm to stage all changes and commit +
+ +### Stop or delete your codespace + +When you are done, remember to stop your codespace on GitHub to avoid any undesired use of your capacity. + +11. Go to github.com/codespaces. At the bottom of the page, all your codespaces are listed. Click the overflow menu icon (more_horiz) for your codespace. + +
+Stop or delete your GitHub Codespace +
+ +12. Click "**Stop codespace**" if you'd like to return to your work later. Otherwise, click "**Delete**." + + +
+ Stop your GitHub codespace +
+
+ Delete your GitHub codespace +
+
diff --git a/data/deploy/community-cloud/manage-your-app/favorite-your-app.md b/data/deploy/community-cloud/manage-your-app/favorite-your-app.md new file mode 100644 index 0000000000000000000000000000000000000000..03051a2f608766c3591219db30c3a85306fe5baa --- /dev/null +++ b/data/deploy/community-cloud/manage-your-app/favorite-your-app.md @@ -0,0 +1,45 @@ +--- +title: Favorite your app +slug: /deploy/streamlit-community-cloud/manage-your-app/favorite-your-app +--- + +# Favorite your app + +Streamlit Community Cloud supports a "favorite" feature that lets you quickly access your apps from your workspace. Favorited apps appear at the top of their workspace with a yellow star (star) beside them. You can favorite and unfavorite apps in any workspace to which you have access as a developer or invited viewer. + +![Favorite apps appear on top in Streamlit Community Cloud](/images/streamlit-community-cloud/workspace-app-favorites-top.png) + + + +Favorites are specific to your account. Other members of your workspace cannot see which apps you have favorited. + + + +## Favoriting and unfavoriting your app + +You can favorite your app: + +- [From your workspace](#favorite-your-app-from-your-workspace). +- [From your app](#favorite-your-app-from-your-app-toolbar)! + +### Favorite your app from your workspace + +1. From your workspace at share.streamlit.io, click the overflow icon (more_vert) next to your app. Click "**Favorite**". + + ![Favorite your app from your workspace](/images/streamlit-community-cloud/workspace-app-favorite.png) + +2. Your favorited app will move to the top of your list (with other favorited apps if you have them) and display with a yellow star. + + ![Favorited app in your workspace](/images/streamlit-community-cloud/workspace-app-favorited.png) + +- Once favorited, from the same menu, click "**Unfavorite**" to remove the star. + + ![Unfavorite your app from your workspace](/images/streamlit-community-cloud/workspace-app-unfavorite.png) + +Alternatively, you can favorite and unfavorite apps by clicking directly on the star next to their names. (Hover over an unfavorited app to reveal an empty star icon next to its name.) + +### Favorite your app from your app toolbar + +From your app at `.streamlit.app`, click the star (star_border/star) in the upper-right corner to toggle your app's favorite status. + +![Favorite your app directly from your live app](/images/streamlit-community-cloud/favorite-select.png) diff --git a/data/deploy/community-cloud/manage-your-app/reboot-your-app.md b/data/deploy/community-cloud/manage-your-app/reboot-your-app.md new file mode 100644 index 0000000000000000000000000000000000000000..f6f6bd82de1fcd64ca21261a707909c4e9646d09 --- /dev/null +++ b/data/deploy/community-cloud/manage-your-app/reboot-your-app.md @@ -0,0 +1,41 @@ +--- +title: Reboot your app +slug: /deploy/streamlit-community-cloud/manage-your-app/reboot-your-app +--- + +# Reboot your app + +If you need to clear your app's memory or force a fresh build after modifying a file that Streamlit Community Cloud doesn't monitor, you may need to reboot your app. This will interrupt any user who may currently be using your app and may take a few minutes for your app to re-deploy. Anyone visiting your app will see "Your app is in the oven" during a reboot. + +Rebooting your app on Streamlit Community Cloud is easy! You can reboot your app: + +- [From your workspace](#reboot-your-app-from-your-workspace). +- [From your Cloud logs](#reboot-your-app-from-your-cloud-logs). + +### Reboot your app from your workspace + +1. From your workspace at share.streamlit.io, click the overflow icon (more_vert) next to your app. Click "**Reboot**". + + ![Reboot your app from your workspace](/images/streamlit-community-cloud/workspace-app-reboot.png) + +2. A confirmation will display. Click "**Reboot**". + +
+Confirm rebooting your app in Streamlit Community Cloud +
+ +### Reboot your app from your Cloud logs + +1. From your app at `.streamlit.app`, click "**Manage app**" in the lower-right corner. + + ![Access Streamlit Community Cloud logs from your app](/images/streamlit-community-cloud/cloud-logs-open.png) + +2. Click the overflow menu icon (more_vert) and click "**Reboot app**". + + ![Reboot your app from your Cloud logs](/images/streamlit-community-cloud/cloud-logs-menu-reboot.png) + +3. A confirmation will display. Click "**Reboot**". + +
+Confirm rebooting your app in Streamlit Community Cloud +
diff --git a/data/deploy/community-cloud/share-your-app/_index.md b/data/deploy/community-cloud/share-your-app/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..50c65451dcd57a038bf109392ad3cf8e910a8bc1 --- /dev/null +++ b/data/deploy/community-cloud/share-your-app/_index.md @@ -0,0 +1,150 @@ +--- +title: Share your app +slug: /deploy/streamlit-community-cloud/share-your-app +--- + +# Share your app + +Now that your app is deployed you can easily share it and collaborate on it. But first, let's take a moment and do a little joy dance for getting that app deployed! 🕺💃 + +Your app is now live at a fixed URL, so go wild and share it with whomever you want. Your app will inherit permissions from your GitHub repo, meaning that if your repo is private your app will be private and if your repo is public your app will be public. If you want to change that you can simply do so from the app settings menu. + +You are only allowed one private app at a time. If you've deployed from a private repository, you will have to make that app public or delete it before you can deploy another app from a private repository. Only developers can change your app between public and private. + +- [Make your app public or private](#make-your-app-public-or-private) +- [Share your public app](#share-your-public-app) +- [Share your private app](#share-your-private-app) + +## Make your app public or private + +If you deployed your app from a public repository, your app will be public by default. If you deployed your app from a private repository, you will need to make the app public if you want to freely share it with the community at large. + +### Set privacy from your app settings + +1. Access your [App settings](/deploy/streamlit-community-cloud/manage-your-app/app-settings) and go to the "**Sharing**" section. + + ![Share settings on Streamlit Community Cloud](/images/streamlit-community-cloud/workspace-app-settings-sharing.png) + +2. Set your app's privacy under "Who can view this app." Select "**This app is public and searchable**" to make your app public. Select "**Only specific people can view this app**" to make your app private. + + ![Set your app's privacy in share settings](/images/streamlit-community-cloud/workspace-app-settings-sharing-change.png) + +### Set privacy from the share button + +1. From your app at `.streamlit.app`, click "**Share**" in the upper-right corner. + + ![Access the share button from your app](/images/streamlit-community-cloud/share-open.png) + +2. Toggle your app between public and private by clicking "**Make this app public**". + + ![Toggle your app between public and private from the share button](/images/streamlit-community-cloud/share-menu-public-toggle.png) + +## Share your public app + +Once your app is public, just give anyone your app's URL and they view it! Streamlit Community Cloud has several convenient shortcuts for sharing your app. + +### Share your app on social media + +1. From your app at `.streamlit.app`, click "**Share**" in the upper-right corner. +2. Click "**Social**" to access convenient social media share buttons. + + ![Social media sharing links from the share button](/images/streamlit-community-cloud/share-menu-social.png) + + + +Use the social media sharing buttons to post your app on our forum! We'd love to see what you make and perhaps feature your app as our app of the month. 💖 + + + +### Invite viewers by email + +Whether your app is public or private, you can send an email invite to your app directly from Streamlit Community Cloud. This grants the viewer access to analytics for all your public apps and the ability to invite other viewers to your workspace. Developers and invited viewers are identified by their email in analytics instead of appearing anonymously (if they view any of your apps while logged in). Read more about viewers in [App analytics](/deploy/streamlit-community-cloud/manage-your-app/app-analytics). + +1. From your app at `.streamlit.app`, click "**Share**" in the upper-right corner. +2. Enter an email address and click "**Invite**". + + ![Invite viewers from the share button](/images/streamlit-community-cloud/share-invite-public.png) + +3. Invited users will get a direct link to your app in their inbox. + + ![Invitation email sent to viewers](/images/streamlit-community-cloud/share-invite-email.png) + +### Copy your app's URL + +You can convenitiently copy your app's URL from the share menu or from your workspace. + +- From your app click "**Share**" in the upper-right corner then click "**Copy link**". + + ![Copy your app's URL from the share button](/images/streamlit-community-cloud/share-copy.png) + +- From your workspace click the overflow menu icon (more_vert) then click "**Copy URL**". + + ![Copy your app's URL from your workspace](/images/streamlit-community-cloud/workspace-app-copy.png) + +### Add a badge to your GitHub repository + +To help others find and play with your Streamlit app, you can add Streamlit's GitHub badge to your repo. Below is an enlarged example of what the badge looks like. Clicking on the badge takes you to—in this case—Streamlit's Roadmap. + +
+ +
+ +Once you deploy your app, you can embed this badge right into your GitHub README.md by adding the following Markdown: + +```markdown +[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://.streamlit.app) +``` + + + +Be sure to replace `https://.streamlit.app` with the URL of your deployed app! + + + +## Share your private app + +By default an app deployed from a private repository will be private to the developers in the workspace. A private app will not be visible to anyone else unless you grant them explicit permission. You can grant permission by adding them as a developer on GitHub or by adding them as a viewer on Streamlit Community Cloud. + +Once you have added someone's email address to your app's viewer list, that person will be able to sign in and view your private app. If their email is associated to a Google account, they will be able to sign in with Google OAuth. Otherwise, they will be able to sign in with single-use, emailed links. Streamlit sends an email invitation with a link to your app every time you invite someone. + + + +When you add a viewer to any app in your workspace, they are granted access to analytics for that app as well as analytics for all your public apps. They can also pass these permissions to others by inviting more viewers. All viewers and developers in your workspace are identified by their email in analytics. Furthermore, their emails show in analytics for every app in your workspace and not just apps they are explicitly invited to. Read more about viewers in [App analytics](/deploy/streamlit-community-cloud/manage-your-app/app-analytics) + + + +### Invite viewers from the share button + +1. From your app at `.streamlit.app`, click "**Share**" in the upper-right corner. + + ![Access the share button from your app](/images/streamlit-community-cloud/share-open.png) + +2. Enter the email to send an invitation to and click "**Invite**". + + ![Invite viewers from the share button](/images/streamlit-community-cloud/share-invite.png) + +3. Invited users appear in the list below. + + ![View invited users from the share button](/images/streamlit-community-cloud/share-invited.png) + +4. Invited users will get a direct link to your app in their inbox. + + ![Invitation email sent to viewers](/images/streamlit-community-cloud/share-invite-email.png) + +- To remove a viewer, simply access the share menu as above and click the close next to their name. + + ![Remove viewers from the share button](/images/streamlit-community-cloud/share-remove.png) + +### Invite viewers from your app settings + +1. Access your [App settings](/deploy/streamlit-community-cloud/manage-your-app/app-settings) and go to the "**Sharing**" section. + + ![Access sharing settings from your app settings](/images/streamlit-community-cloud/workspace-app-settings-sharing.png) + +2. Add or remove users from the list of viewers. Click "**Save**". + + ![Invite and remove viewers from your app settings](/images/streamlit-community-cloud/workspace-app-settings-sharing-invite.png) diff --git a/data/deploy/community-cloud/share-your-app/embed-your-app.md b/data/deploy/community-cloud/share-your-app/embed-your-app.md new file mode 100644 index 0000000000000000000000000000000000000000..1cfa81be4bd7fe0370cc775716554deb3ac7a541 --- /dev/null +++ b/data/deploy/community-cloud/share-your-app/embed-your-app.md @@ -0,0 +1,158 @@ +--- +title: Embed your app +slug: /deploy/streamlit-community-cloud/share-your-app/embed-your-app +--- + +# Embed your app + +Embedding Streamlit Community Cloud apps enriches your content by integrating interactive, data-driven applications directly within your pages. Whether you're writing a blog post, a technical document, or sharing resources on platforms like Medium, Notion, or even StackOverflow, embedding Streamlit apps adds a dynamic component to your content. This allows your audience to interact with your ideas, rather than merely reading about them or looking at screenshots. + +Streamlit Community Cloud supports both [iframe](#embedding-with-iframes) and [oEmbed](#embedding-with-oembed) methods for embedding **public** apps. This flexibility enables you to share your apps across a wide array of platforms, broadening your app's visibility and impact. In this guide, we'll cover how to use both methods effectively to share your Streamlit apps with the world. + +## Embedding with iframes + +Streamlit Community Cloud supports embedding **public** apps using the subdomain scheme. To embed a public app, add the query parameter `/?embed=true` to the end of the `*.streamlit.app` URL. + +For example, say you want to embed the 30DaysOfStreamlit app. The URL to include in your iframe is: `https://30days.streamlit.app/?embed=true`: + +```javascript + +``` + + + + + +There will be no official support for embedding private apps. + + + +In addition to allowing you to embed apps via iframes, the `?embed=true` query parameter also does the following: + +- Removes the toolbar with the app menu icon (more_vert). +- Removes the padding at the top and bottom of the app. +- Removes the footer. +- Removes the colored line from the top of the app. + +For granular control over the embedding behavior, Streamlit allows you to specify one or more instances of the `?embed_options` query parameter (e.g. to show the toolbar, open the app in dark theme, etc). [Click here for a full list of Embed options.](#embed-options) + +## Embedding with oEmbed + +Streamlit's oEmbed support allows for a simpler embedding experience. You can directly drop a Streamlit app's URL into a Medium, Ghost, or Notion page (or any of more than 700 content providers that supports oEmbed or embed.ly). The embedded app will automatically appear! This helps Streamlit Community Cloud apps seamlessly integrate into these platforms, improving the visibility and accessibility of your apps. + +### Example + +When creating content in a Notion page, Medium article, or Ghost blog, you only need to paste the app's URL and hit "**Enter**". The app will then render automatically at that spot in your content. You can use your undecorated app URL without the `?embed=true` query parameter. + +``` +https://30days.streamlit.app/ +``` + +Here's an example of @chrieke's Prettymapp app embedded in a Medium article: + +Example: Embed an app in a Medium article with oEmbed + + + +Ensure the platform hosting the embedded Streamlit app supports oEmbed or embed.ly. + + + +### Key Sites for oEmbed + +oEmbed should work out of the box for several platforms including but not limited to: + +- Medium +- Notion +- Looker +- Tableau +- Ghost +- Discourse +- StackOverflow +- W3 +- Reddit + +Please check the specific platform's documentation to verify support for oEmbed. + +### iframe versus oEmbed + +The only noteworthy differences between the methods is that iframing allows you to customize the app's embedding behavior (e.g. showing the toolbar, opening the app in dark theme, etc) using the various `?embed_options` described in the next section. + +## Embed options + +When [Embedding with iframes](#embedding-with-iframes), Streamlit allows you to specify one or more instances of the `?embed_options` query parameter for granular control over the embedding behavior. + +Both `?embed` and `?embed_options` are invisible to [`st.query_params`](/develop/api-reference/caching-and-state/st.query_params) and its precursors, [`st.experimental_get_query_params`](/develop/api-reference/caching-and-state/st.experimental_get_query_params) and [`st.experimental_set_query_params`](/develop/api-reference/caching-and-state/st.experimental_set_query_params). You can't get or set their values. + +The supported values for `?embed_options` are listed below: + +1. Show the toolbar at the top right of the app which includes the app menu (more_vert), running man, and link to GitHub. + + ```javascript + /?embed=true&embed_options=show_toolbar + ``` + +2. Show padding at the top and bottom of the app. + + ```javascript + /?embed=true&embed_options=show_padding + ``` + +3. Show the footer reading "Made with Streamlit." (This doesn't apply to Streamlit versions 1.29.0 and later since the footer was removed from the library.) + + ```javascript + /?embed=true&embed_options=show_footer + ``` + +4. Show the colored line at the top of the app. + + ```javascript + /?embed=true&embed_options=show_colored_line + ``` + +5. Hide the "skeleton" that appears while an app is loading. + + ```javascript + /?embed=true&embed_options=hide_loading_screen + ``` + +6. Disable scrolling for the main body of the app. (The sidebar will still be scrollable.) + + ```javascript + /?embed=true&embed_options=disable_scrolling + ``` + +7. Open the app with light theme. + + ```javascript + /?embed=true&embed_options=light_theme + ``` + +8. Open the app with dark theme. + + ```javascript + /?embed=true&embed_options=dark_theme + ``` + +You can also combine the params: + +```javascript +/?embed=true&embed_options=show_toolbar&embed_options=show_padding&embed_options=show_footer&embed_options=show_colored_line&embed_options=disable_scrolling +``` + +### Build an embed link + +You can conveniently build an embed link for your app — right from your app! + +1. From your app at `.streamlit.app`, click "**Share**" in the upper-right corner. +2. Click "**Embed**" to access a list of selectable embed options. + + ![Access embed options from the share button](/images/streamlit-community-cloud/share-menu-embed.png) + +3. Select your embed options and click "**Get embed link**" to copy the embed link to your clipboard. + + ![Build a customized embed link for your app from the share button](/images/streamlit-community-cloud/share-menu-embed-url.png) diff --git a/data/deploy/community-cloud/share-your-app/indexability.md b/data/deploy/community-cloud/share-your-app/indexability.md new file mode 100644 index 0000000000000000000000000000000000000000..46607735c9d8976a82ec1cb0d4f005cfb7cc3021 --- /dev/null +++ b/data/deploy/community-cloud/share-your-app/indexability.md @@ -0,0 +1,65 @@ +--- +title: SEO and search indexability +slug: /deploy/streamlit-community-cloud/share-your-app/indexability +--- + +# SEO and search indexability + +When you deploy a public app to Streamlit Community Cloud, it is automatically indexed by search engines like Google and Bing on a weekly basis. 🎈 This means that anyone can find your app by searching for its custom subdomain (e.g. "traingenerator.streamlit.app") or by searching for the app's title. + +## Get the most out of app indexability + +Here are some tips to help you get the most out of app indexability: + +1. [Make sure your app is public](#make-sure-your-app-is-public) +2. [Choose a custom subdomain early](#choose-a-custom-subdomain-early) +3. [Choose a descriptive app title](#choose-a-descriptive-app-title) +4. [Customize your app's meta description](#customize-your-apps-meta-description) + +### Make sure your app is public + +All public apps hosted on Streamlit Community Cloud are indexed by search engines. If your app is private, it will not be indexed by search engines. To make your private app public, read [Share your app](/deploy/streamlit-community-cloud/share-your-app). + +### Choose a custom subdomain early + +Streamlit Community Cloud automatically generates a random subdomain for your app. However, subdomains are customizable! Custom subdomains modify your app URLs to reflect your app content, personal branding, or whatever you’d like. Read more about custom subdomains in [Custom subdomains](/deploy/streamlit-community-cloud/deploy-your-app#custom-subdomains). + +By choosing a custom subdomain, you can use it to help people find your app. For example, if you're deploying an app that generates training data, you might choose a subdomain like `traingenerator.streamlit.app`. This makes it easy for people to find your app by searching for "training generator" or "train generator streamlit app." + +We recommend choosing a custom subdomain when you deploy your app. This ensures that your app is indexed by search engines using your custom subdomain, rather than the automatically generated one. If you choose a custom subdomain later, your app may be indexed multiple times—once using the default subdomain and once using your custom subdomain. In this case, your old URL will result in a 404 error which can confuse users who are searching for your app. + +### Choose a descriptive app title + +The meta title of your app is the text that appears in search engine results. It is also the text that appears in the browser tab when your app is open. By default, the meta title of your app is the same as the title of your app. However, you can customize the meta title of your app by setting the [`st.set_page_config`](/develop/api-reference/configuration/st.set_page_config) parameter `page_title` to a custom string. For example: + +```python +st.set_page_config(page_title="Traingenerator") +``` + +This will change the meta title of your app to "Traingenerator." This makes it easier for people to find your app by searching for "Traingenerator" or "train generator streamlit app": + + + +### Customize your app's meta description + +Meta descriptions are the short descriptions that appear in search engine results. Search engines use the meta description to help users understand what your app is about. + +From our observations, search engines seem to favor the content in both `st.header` and `st.text` over `st.title`. If you put a description at the top of your app under `st.header` or `st.text`, there’s a good chance search engines will use this for the meta description. + +## What does my indexed app look like? + +If you're curious about what your app looks like in search engine results, you can type the following into Google Search: + +``` +site:.streamlit.app +``` + +Example: `site:traingenerator.streamlit.app` + + + +## What if I don't want my app to be indexed? + +If you don't want your app to be indexed by search engines, you can make it private. Read [Share your app](/deploy/streamlit-community-cloud/share-your-app) to learn more about making your app private. Note: each workspace can only have one private app. If you want to make your app private, you must first delete any other private app in your workspace or make it public. + +That said, Streamlit Community Cloud is an open and free platform for the community to deploy, discover, and share Streamlit apps and code with each other. As such, we encourage you to make your app public so that it can be indexed by search engines and discovered by other Streamlit users and community members. diff --git a/data/deploy/community-cloud/share-your-app/share-previews.md b/data/deploy/community-cloud/share-your-app/share-previews.md new file mode 100644 index 0000000000000000000000000000000000000000..f4d433aa617e96bb4dc1af9ae445ac961e185d80 --- /dev/null +++ b/data/deploy/community-cloud/share-your-app/share-previews.md @@ -0,0 +1,62 @@ +--- +title: Share previews +slug: /deploy/streamlit-community-cloud/share-your-app/share-previews +--- + +# Share previews + +Social media sites generate a card with a title, preview image, and description when you share a link. This feature is called a "share preview." In the same way, when you share a link to a public Streamlit app on social media, a share preview is also generated. Here's an example of a share preview for a public Streamlit app posted on Twitter: + +
+ + + +
+ + + +Share previews are generated only for public apps deployed on Streamlit Community Cloud. + + + +## Titles + +The title is the text that appears at the top of the share preview. The text also appears in the browser tab when you visit the app. You should set the title to something that will make sense to your app's audience and describe what the app does. It is best practice to keep the title concise, ideally under 60 characters. + +There are two ways to set the title of a share preview: + +1. Set the `page_title` parameter in [`st.set_page_config()`](/develop/api-reference/configuration/st.set_page_config) to your desired title. E.g.: + + ```python + import streamlit as st + + st.set_page_config(page_title="My App") + + # ... rest of your app + ``` + +2. If you don't set the `page_title` parameter, the title of the share preview will be the name of your app's GitHub repository. For example, the default title for an app hosted on GitHub at github.com/jrieke/traingenerator will be "traingenerator". + +## Descriptions + +The description is the text that appears below the title in the share preview. The description should summarize what the app does and ideally should be under 100 characters. + +Streamlit pulls the description from the README in the app's GitHub repository. If there is no README, the description will default to: + +_This app was built in Streamlit! Check it out and visit https://streamlit.io for more awesome community apps. 🎈_ + +
+ + + +
+ +If you want your share previews to look great and want users to share your app and click on your links, you should write a good description in the README of your app’s GitHub repository. + +## Preview images + +Streamlit Community Cloud takes a screenshot of your app once a day and uses it as the preview image, unlike titles and descriptions which are pulled directly from your app's code or GitHub repository. This screenshot may take up to 24 hours to update. + +### Switching your app from public to private + +If you initially made your app public and later decided to make it private, we will stop generating share previews for the app. However, it may take up to 24 hours for the share previews to stop appearing. diff --git a/data/deploy/community-cloud/troubleshooting.md b/data/deploy/community-cloud/troubleshooting.md new file mode 100644 index 0000000000000000000000000000000000000000..e40125e5455e499987696831416c92882f44c8c1 --- /dev/null +++ b/data/deploy/community-cloud/troubleshooting.md @@ -0,0 +1,153 @@ +--- +title: Troubleshooting +slug: /deploy/streamlit-community-cloud/troubleshooting +--- + +# Troubleshooting + +Sorry to hear you're having issues! Please take a look at some frequently asked questions and issues below. If you cannot find an answer to your issue, please post on our [Community forum](http://discuss.streamlit.io) so that our engineers or community members can help you. + +## Table of contents + +1. [General help](#general-help) +2. [Deploying apps](#deploying-apps) +3. [Sharing and accessing apps](/deploy/streamlit-community-cloud/troubleshooting#sharing-and-accessing-apps) +4. [Data and app security](/deploy/streamlit-community-cloud/troubleshooting#data-and-app-security) +5. [GitHub integration](/deploy/streamlit-community-cloud/troubleshooting#github-integration) +6. [Limitations and known issues](/deploy/streamlit-community-cloud/troubleshooting#limitations-and-known-issues) + +## General help + +### How can I get help with my app? + +If you have any questions, feedback, run into any issues, or need to reach us, you can ask on our [Community forum](https://discuss.streamlit.io/). This is best suited for any questions related to the open source library and Community Cloud - debugging code, deployment, resource limits, etc. + +## Deploying apps + +### My repo isn't showing on the Deploy page + +It's possible it just isn't showing up even though it is already there. Try typing it in. If we don't recognize it, you'll see the message below with a link to click and give access. + +![Troubleshooting deploy page](/images/streamlit-community-cloud/troubleshooting-deploy-page.png) + +If for some reason that doesn't work, please try logging out and back in again to make sure the change took effect. And if that doesn't work - please let us know and we'll get you sorted! + +### It won't let me deploy the app + +To deploy an app for the first time you must have admin-level access to the repo in GitHub. Please check with your administrator to make sure you have that access. If not, please ask them to deploy for the first time (we need this in order to establish webhooks for continuous integration) and from there you can then push updates to the app. + +### I need to set a specific Python version for my app + +When deploying an app, under advanced settings, you can choose which version of Python you wish your app to use. + +![Streamlit Community Cloud Advanced settings](/images/streamlit-community-cloud/deploy-an-app-advanced.png) + +### How do I store files locally? + +If you want to store your data locally as opposed to in a database, you can store the file in your GitHub repository. Streamlit is just python, so you can read the file using: + +`pandas.read_csv("data.csv")` or `open("data.csv")` + + + +If you have really big or binary data that you change frequently, and git is feeling slow, you might want to check out [Git Large File Store (LFS)](https://git-lfs.github.com/) as a better way to store large files in GitHub. You don't need to make any changes to your app to start using it. If your GitHub repo uses LFS, it will now _just work_ with Streamlit. + + + +### My app is running into issues while deploying + +Check your Cloud logs by clicking on the "Manage app" expander in the bottom right corner of your screen. Often the trouble is due to a dependency not being declared. See here for [more information on dependency management](/deploy/streamlit-community-cloud/deploy-your-app/app-dependencies). + +If that's not the issue, then please send the logs and warning you are seeing to our [Community forum](https://discuss.streamlit.io/) and we'll help get you sorted! + +### My app is hitting resource limits / my app is running very slowly + +If your app is running slowly or you're hitting the 'Argh' page, we first highly recommend going through and implementing the suggestions in the following blog posts to prevent your app from hitting the resource limits and to detect if your Streamlit app leaks memory: + +- [Common app problems: Resource limits](https://blog.streamlit.io/common-app-problems-resource-limits/) +- [3 steps to fix app memory leaks](https://blog.streamlit.io/3-steps-to-fix-app-memory-leaks/) + +If you're still having issues, click [here](/deploy/streamlit-community-cloud/manage-your-app#app-resources-and-limits) to learn more about resource limits. + +### Can I get a custom URL for my app? + +Yes! You can find [instructions for setting a custom subdomain here](/knowledge-base/deploy/custom-subdomains). + +## Sharing and accessing apps + +Don't have SSO? No problem! You can sign in to Streamlit with your email address. [Click here](/deploy/streamlit-community-cloud/get-started#sign-in-with-email) for step-by-step instructions on how to sign in with email. \*/} + +### How do I add viewers to my Streamlit apps? + +Viewer auth allows you to restrict the viewers of your private app. To access your app, users have to authenticate using an email-based passwordless login or Google OAuth. To learn more about how to share your public and private apps with viewers, click [here](/deploy/streamlit-community-cloud/share-your-app). + +### Do viewers need access to the GitHub repo? + +Nope! You only need access to the GitHub repo if you want to push changes to the app. + +### What will unauthorized/logged out viewers see when they view my app? + +A 404 error is displayed to unauthorized viewers to avoid providing any unnecessary information about your app to unintended viewers. Users who satisfy any of the following conditions will see a 404 error when attempting to view your app after you have configured viewer auth: + +- User is not logged in with their primary identity. +- User is not included in the [list of allowed viewers](/deploy/streamlit-community-cloud/share-your-app#share-your-private-app) provided in the app settings. +- User lacks read access to your app's GitHub repo. +- User has read access to your app's GitHub repo but is not enrolled in Streamlit Community Cloud. + +![Four Oh Four](/images/streamlit-community-cloud/404.png) + +### I've added someone to the viewer list but they still see a 404 error when attempting to view the app + +If a user is still seeing a 404 error after their email address has been added to the viewer list, we recommend that you: + +- Check that the user did not log into a different Google account via Single Sign-On (if you have added their work email address to the viewer list, ask the user to check that they are not logged into their personal Google account, and vice versa). +- Check that the user has navigated to the correct URL. +- Check that the user's email address has been entered correctly in the viewer list. +- Reach out on our [Community forum](https://discuss.streamlit.io/) and we will be happy to help. + +## Data and app security + +### How will Streamlit secure my data? + +Streamlit takes a number of industry best-practice measures to ensure your code, data, and apps are all secure. Read more in our [Trust and Security memo](/deploy/streamlit-community-cloud/get-started/trust-and-security). + +### How do I set up SSO for my organization? + +Community Cloud uses Google OAuth, by default. If you use Google for authentication you're all set. + +## Billing and administration + +The Community Cloud is a free service. You don't have to worry about setting up billing or being charged. + +## GitHub integration + +### Why does Streamlit require additional OAuth scope? + +In order to deploy your app, Streamlit requires access to your app's source code in GitHub and also the ability to manage the public keys associated with the repositories. The default GitHub OAuth scopes are sufficient to work with apps in public GitHub repositories. However, in order to work with apps in private GitHub repositories, Streamlit requires the additional `repo` OAuth scope from GitHub. We recognize that this scope provides Streamlit with extra permissions that we do not really need, and which, as people who prize security, we'd rather not even be granted. Alas, we need to work with the APIs we are provided by GitHub. + +### After deploying my private-repo app, I received an email from GitHub saying a new public key was added to my repo. Is this expected? + +**This is the expected behavior**. When you try to deploy an app that lives in a private repo, Streamlit Community Cloud needs to get access to that repo somehow. For this, we create a read-only [GitHub Deploy Key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) then access your repo using a public SSH key. When we set this up, GitHub notifies admins of the repo that the key was created as a security measure. + +### What happens when a user's permissions change on GitHub? + +Once a user is added to a repository on GitHub, it will take at most 15 minutes before they can deploy the app on Cloud. If a user is removed from a repository on GitHub, it will take at most 15 minutes before their permissions to manage the app from that repository are revoked. + +## Limitations and known issues + +Here are some limitations and known issues that we're actively working to resolve. + +- When you print something to the Cloud logs, you may need to do a `sys.stdout.flush()` before it shows up. +- Matplotlib [doesn't work well with threads](https://matplotlib.org/3.3.2/faq/howto_faq.html#working-with-threads). So if you're using Matplotlib you should wrap your code with locks as shown in the snippet below. This Matplotlib bug is more prominent when you share your app apps since you're more likely to get more concurrent users then. + + ```python + from matplotlib.backends.backend_agg import RendererAgg + _lock = RendererAgg.lock + + with _lock: + fig.title('This is a figure)') + fig.plot([1,20,3,40]) + st.pyplot(fig) + ``` + +- All apps are hosted in the United States. This is currently not configurable. diff --git a/data/deploy/concepts/_index.md b/data/deploy/concepts/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..ac0b5722a24f290398a3e006707bca7923b05ffd --- /dev/null +++ b/data/deploy/concepts/_index.md @@ -0,0 +1,29 @@ +--- +title: Deployment concepts +slug: /deploy/concepts +--- + +# Deployment concepts + +Learn the fundamental concepts of app deployment. There are three main processes involved in deploying apps. + +- Install Python, Streamlit, and other dependencies in your deployment environment. +- Securely handle your secrets and private information. +- Remote start your app (`streamlit run`). + +If you're using Streamlit Community Cloud, we'll do most of the work for you! + + + Understand the basics of configuring your deployment environment. + Understand the basics of secret management. + diff --git a/data/deploy/concepts/dependencies.md b/data/deploy/concepts/dependencies.md new file mode 100644 index 0000000000000000000000000000000000000000..aca2e1f1c4880c6bcb70200dc56f362b46e5e9ac --- /dev/null +++ b/data/deploy/concepts/dependencies.md @@ -0,0 +1,55 @@ +--- +title: Managing dependencies when deploying your app +slug: /deploy/concepts/dependencies +--- + +# Managing dependencies when deploying your app + +Before you began developing your app, you set up and configured your development environment by installing Python and Streamlit. When you deploy your app, you need to set up and configure your deployment environment in the same way. When you deploy your app to a cloud service, your app's [Python server](/develop/concepts/architecture/architecture#python-backend-server) will be running on a remote machine. This remote machine will not have access all the files and programs on your personal computer. + +All Streamlit apps have at least two dependencies: Python and Streamlit. Your app may have additional dependencies in the form of Python packages or software that must be installed to properly execute your script. If you are using a service like Streamlit Community Cloud which is designed for Streamlit apps, we'll take care of Python and Streamlit for you! + +## Install Python and other software + +If you are using Streamlit Community Cloud, Python is already installed. You can just pick the version in the deployment dialog. If you need to install Python yourself or you have other non-Python software to install, follow your platform's instructions to install additional software. You will commonly use a package management tool to do this. +For example, Streamlit Community Cloud uses Advanced Package Tool (`apt`) for Debian-based Linux systems. For more information about installing non-Python depencies on Streamlit Community Cloud, see [`apt-get` dependencies](/deploy/streamlit-community-cloud/deploy-your-app/app-dependencies#apt-get-dependencies). + +## Install Python packages + +Once you have Python installed in your deployment environment, you'll need to install all the necessary Python packages, including Streamlit! With each `import` of an installed package, you add a Python dependency to your script. You need to install those dependencies in your deployment environment through a Python package manager. + +If you are using Streamlit Community Cloud, you'll have the latest version of Streamlit and all of its dependencies installed by default. So, if you're making a simple app and don't need additional dependencies, you won't have to do anything at all! + +### `pip` and `requirements.txt` + +Since `pip` comes by default with Python, the most common way to configure your Python environment is with a `requirements.txt` file. Each line of a `requirements.txt` file is a package to `pip install`. You should _not_ include built-in Python libraries like `math` or `random` in your `requirements.txt` file. These are a part of Python and aren't installed separately. + +If you have a script like the following, you would only need to install Streamlit. No extra dependencies would be needed since `pandas` and `numpy` are installed as direct dependencies of `streamlit`. Similarly, `math` and `random` are built into Python. + +```python +import streamlit as st +import pandas as pd +import numpy as np +import math +import random + +st.write('Hi!') +``` + +However, it's a best practice accurately record packages you use, so the recommended `requirements.txt` file would be: + +```none +streamlit +pandas +numpy +``` + +If you needed to specify certain versions, another valid example would be: + +```none +streamlit==1.24.1 +pandas>2.0 +numpy<=1.25.1 +``` + +A `requirements.txt` file is commonly saved in the root of your repository or file directory. If you are using Streamlit Community Cloud, see [Add Python dependencies](/deploy/streamlit-community-cloud/deploy-your-app/app-dependencies#add-python-dependencies) for more information. Otherwise, check your platform's documentation. diff --git a/data/deploy/concepts/secrets.md b/data/deploy/concepts/secrets.md new file mode 100644 index 0000000000000000000000000000000000000000..1b4d3a3c17ae7a0c8db347d58c821037b4208038 --- /dev/null +++ b/data/deploy/concepts/secrets.md @@ -0,0 +1,14 @@ +--- +title: Managing secrets when deploying your app +slug: /deploy/concepts/secrets +--- + +# Managing secrets when deploying your app + +If you are connecting to data sources or external services, you will likely be handling secret information like credentials or keys. Secret information should be stored and transmitted in a secure manner. When you deploy your app, ensure that you understand your platform's features and mechanisms for handling secrets so you can follow best practice. + +Avoid saving secrets directly in your code and keep `.gitignore` updated to prevent accidentally committing a local secret to your repository. For helpful reminders, see [Security reminders](/develop/concepts/connections/security-reminders). + +If you are using Streamlit Community Cloud, [Secrets management](/deploy/streamlit-community-cloud/deploy-your-app/secrets-management) allows you save environment variables and store secrets outside of your code. If you are using another platform designed for Streamlit, check if they have a built-in mechanism for working with secrets. In some cases, they may even support `st.secrets` or securely uploading your `secrets.toml` file. + +For information about using `st.connection` with environment variables, see [Global secrets, managing multiple apps and multiple data stores](/develop/concepts/connections/connecting-to-data#global-secrets-managing-multiple-apps-and-multiple-data-stores). diff --git a/data/deploy/tutorials/_index.md b/data/deploy/tutorials/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..fc698d394ae57001e317e5d92fb30a45d98979e6 --- /dev/null +++ b/data/deploy/tutorials/_index.md @@ -0,0 +1,44 @@ +--- +title: Deployment tutorials +slug: /deploy/tutorials +--- + +# Deployment tutorials + +This sections contains step-by-step guides on how to deploy Streamlit apps to various cloud platforms and services. We have deployment guides for: + + + + +screenshot + +
Streamlit Community Cloud
+ +
+ + + +screenshot + +
Docker
+ +
+ + + +screenshot + +
Kubernetes
+ +
+
+ +While we work on official Streamlit deployment guides for other hosting providers, here are some user-submitted tutorials for different cloud services: + +- [How to Deploy Streamlit to a Free **Amazon EC2** instance](https://towardsdatascience.com/how-to-deploy-a-streamlit-app-using-an-amazon-free-ec2-instance-416a41f69dc3), by Rahul Agarwal. +- [Host Streamlit on **Azure**](https://towardsdatascience.com/deploying-a-streamlit-web-app-with-azure-app-service-1f09a2159743), by Richard Peterson. +- [How to deploy Streamlit apps to **Google App Engine**](https://dev.to/whitphx/how-to-deploy-streamlit-apps-to-google-app-engine-407o), by [Yuichiro Tachibana (Tsuchiya)](https://discuss.streamlit.io/u/whitphx/summary). +- [Host Streamlit on **Heroku**](https://towardsdatascience.com/quickly-build-and-deploy-an-application-with-streamlit-988ca08c7e83), by Maarten Grootendorst. +- [Deploy Streamlit on **Ploomber Cloud**](https://docs.cloud.ploomber.io/en/latest/apps/streamlit.html), by Ido Michael. +- [Host Streamlit on **21YunBox**](https://www.21yunbox.com/docs/#/deploy-streamlit), by Toby Lei. +- [Community-supported deployment wiki](https://discuss.streamlit.io/t/streamlit-deployment-guide-wiki/5099). diff --git a/data/deploy/tutorials/docker.md b/data/deploy/tutorials/docker.md new file mode 100644 index 0000000000000000000000000000000000000000..0758a67638364fae49ce9bd109a00e8434d15863 --- /dev/null +++ b/data/deploy/tutorials/docker.md @@ -0,0 +1,265 @@ +--- +title: Deploy Streamlit using Docker +slug: /deploy/tutorials/docker +--- + +# Deploy Streamlit using Docker + +## Introduction + +So you have an amazing app and you want to start sharing it with other people, what do you do? You have a few options. First, where do you want to run your Streamlit app, and how do you want to access it? + +- **On your corporate network** - Most corporate networks are closed to the outside world. You typically use a VPN to log onto your corporate network and access resources there. You could run your Streamlit app on a server in your corporate network for security reasons, to ensure that only folks internal to your company can access it. +- **On the cloud** - If you'd like to access your Streamlit app from outside of a corporate network, or share your app with folks outside of your home network or laptop, you might choose this option. In this case, it'll depend on your hosting provider. We have [community-submitted guides](/knowledge-base/deploy/deploy-streamlit-heroku-aws-google-cloud) from Heroku, AWS, and other providers. + +Wherever you decide to deploy your app, you will first need to containerize it. This guide walks you through using Docker to deploy your app. If you prefer Kubernetes see [Deploy Streamlit using Kubernetes](/deploy/tutorials/kubernetes). + +## Prerequisites + +1. [Install Docker Engine](#install-docker-engine) +2. [Check network port accessibility](#check-network-port-accessibility) + +### Install Docker Engine + +If you haven't already done so, install [Docker](https://docs.docker.com/engine/install/#server) on your server. Docker provides `.deb` and `.rpm` packages from many Linux distributions, including: + +- [Debian](https://docs.docker.com/engine/install/debian/) +- [Ubuntu](https://docs.docker.com/engine/install/ubuntu/) + +Verify that Docker Engine is installed correctly by running the `hello-world` Docker image: + +```bash +sudo docker run hello-world +``` + + + +Follow Docker's official [post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/) to run Docker as a non-root user, so that you don't have to preface the `docker` command with `sudo`. + + + +### Check network port accessibility + +As you and your users are behind your corporate VPN, you need to make sure all of you can access a certain network port. Let's say port `8501`, as it is the default port used by Streamlit. Contact your IT team and request access to port `8501` for you and your users. + +## Create a Dockerfile + +Docker builds images by reading the instructions from a `Dockerfile`. A `Dockerfile` is a text document that contains all the commands a user could call on the command line to assemble an image. Learn more in the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/). The [docker build](https://docs.docker.com/engine/reference/commandline/build/) command builds an image from a `Dockerfile`. The [docker run](https://docs.docker.com/engine/reference/commandline/run/) command first creates a container over the specified image, and then starts it using the specified command. + +Here's an example `Dockerfile` that you can add to the root of your directory. i.e. in `/app/` + +```docker +# app/Dockerfile + +FROM python:3.9-slim + +WORKDIR /app + +RUN apt-get update && apt-get install -y \ + build-essential \ + curl \ + software-properties-common \ + git \ + && rm -rf /var/lib/apt/lists/* + +RUN git clone https://github.com/streamlit/streamlit-example.git . + +RUN pip3 install -r requirements.txt + +EXPOSE 8501 + +HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health + +ENTRYPOINT ["streamlit", "run", "streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"] +``` + +### Dockerfile walkthrough + +Let’s walk through each line of the Dockerfile : + +1. A `Dockerfile` must start with a [`FROM`](https://docs.docker.com/engine/reference/builder/#from) instruction. It sets the [Base Image](https://docs.docker.com/glossary/#base-image) (think OS) for the container: + + ```docker + FROM python:3.9-slim + ``` + + Docker has a number of official Docker base images based on various Linux distributions. They also have base images that come with language-specific modules such as [Python](https://hub.docker.com/_/python). The `python` images come in many flavors, each designed for a specific use case. Here, we use the `python:3.9-slim` image which is a lightweight image that comes with the latest version of Python 3.9. + + + + You can also use your own base image, provided the image you use contains a [supported version of Python](/knowledge-base/using-streamlit/sanity-checks#check-0-are-you-using-a-streamlit-supported-version-of-python) for Streamlit. There is no one-size-fits-all approach to using any specific base image, nor is there an official Streamlit-specific base image. + + + +2. The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the `Dockerfile` . Let’s set it to `app/` : + + ```docker + WORKDIR /app + ``` + + + + As mentioned in [Development flow](/get-started/fundamentals/main-concepts#development-flow), for Streamlit version 1.10.0 and higher, Streamlit apps cannot be run from the root directory of Linux distributions. Your main script should live in a directory other than the root directory. If you try to run a Streamlit app from the root directory, Streamlit will throw a `FileNotFoundError: [Errno 2] No such file or directory` error. For more information, see GitHub issue [#5239](https://github.com/streamlit/streamlit/issues/5239). + + If you are using Streamlit version 1.10.0 or higher, you must set the `WORKDIR` to a directory other than the root directory. For example, you can set the `WORKDIR` to `/app` as shown in the example `Dockerfile` above. + + +3. Install `git` so that we can clone the app code from a remote repo: + + ```docker + RUN apt-get update && apt-get install -y \ + build-essential \ + curl \ + software-properties-common \ + git \ + && rm -rf /var/lib/apt/lists/* + ``` + +4. Clone your code that lives in a remote repo to `WORKDIR`: + + a. If your code is in a public repo: + + ```docker + RUN git clone https://github.com/streamlit/streamlit-example.git . + ``` + + Once cloned, the directory of `WORKDIR` will look like the following: + + ```bash + app/ + - requirements.txt + - streamlit_app.py + ``` + + where `requirements.txt` file contains all your [Python dependencies](/deploy/streamlit-community-cloud/deploy-your-app/app-dependencies#add-python-dependencies). E.g + + ``` + altair + pandas + streamlit + ``` + + and `streamlit_app.py` is your main script. E.g. + + ```python + from collections import namedtuple + import altair as alt + import math + import pandas as pd + import streamlit as st + + """ + # Welcome to Streamlit! + + Edit `/streamlit_app.py` to customize this app to your heart's desire :heart: + + If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community + forums](https://discuss.streamlit.io). + + In the meantime, below is an example of what you can do with just a few lines of code: + """ + + with st.echo(code_location='below'): + total_points = st.slider("Number of points in spiral", 1, 5000, 2000) + num_turns = st.slider("Number of turns in spiral", 1, 100, 9) + + Point = namedtuple('Point', 'x y') + data = [] + + points_per_turn = total_points / num_turns + + for curr_point_num in range(total_points): + curr_turn, i = divmod(curr_point_num, points_per_turn) + angle = (curr_turn + 1) * 2 * math.pi * i / points_per_turn + radius = curr_point_num / total_points + x = radius * math.cos(angle) + y = radius * math.sin(angle) + data.append(Point(x, y)) + + st.altair_chart(alt.Chart(pd.DataFrame(data), height=500, width=500) + .mark_circle(color='#0068c9', opacity=0.5) + .encode(x='x:Q', y='y:Q')) + ``` + + b. If your code is in a private repo, please read [Using SSH to access private data in builds](https://docs.docker.com/develop/develop-images/build_enhancements/#using-ssh-to-access-private-data-in-builds) and modify the Dockerfile accordingly -- to install an SSH client, download the public key for [github.com](https://github.com), and clone your private repo. If you use an alternative VCS such as GitLab or Bitbucket, please consult the documentation for that VCS on how to copy your code to the `WORKDIR` of the Dockerfile. + + c. If your code lives in the same directory as the Dockerfile, copy all your app files from your server into the container, including `streamlit_app.py`, `requirements.txt`, etc, by replacing the `git clone` line with: + + ```docker + COPY . . + ``` + + More generally, the idea is copy your app code from wherever it may live on your server into the container. If the code is not in the same directory as the Dockerfile, modify the above command to include the path to the code. + +5. Install your app’s [Python dependencies](/deploy/streamlit-community-cloud/deploy-your-app/app-dependencies#add-python-dependencies) from the cloned `requirements.txt` in the container: + + ```docker + RUN pip3 install -r requirements.txt + ``` + +6. The [`EXPOSE`](https://docs.docker.com/engine/reference/builder/#expose) instruction informs Docker that the container listens on the specified network ports at runtime. Your container needs to listen to Streamlit’s (default) port 8501: + + ```docker + EXPOSE 8501 + ``` + +7. The [`HEALTHCHECK`](https://docs.docker.com/engine/reference/builder/#expose) instruction tells Docker how to test a container to check that it is still working. Your container needs to listen to Streamlit’s (default) port 8501: + + ```docker + HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health + ``` + +8. An [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) allows you to configure a container that will run as an executable. Here, it also contains the entire `streamlit run` command for your app, so you don’t have to call it from the command line: + + ```docker + ENTRYPOINT ["streamlit", "run", "streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"] + ``` + +## Build a Docker image + +The [`docker build`](https://docs.docker.com/engine/reference/commandline/build/) command builds an image from a `Dockerfile` . Run the following command from the `app/` directory on your server to build the image: + +```docker +docker build -t streamlit . +``` + +The `-t` flag is used to tag the image. Here, we have tagged the image `streamlit`. If you run: + +```docker +docker images +``` + +You should see a `streamlit` image under the REPOSITORY column. For example: + +``` +REPOSITORY TAG IMAGE ID CREATED SIZE +streamlit latest 70b0759a094d About a minute ago 1.02GB +``` + +## Run the Docker container + +Now that you have built the image, you can run the container by executing: + +```docker +docker run -p 8501:8501 streamlit +``` + +The `-p` flag publishes the container’s port 8501 to your server’s 8501 port. + +If all went well, you should see an output similar to the following: + +``` +docker run -p 8501:8501 streamlit + + You can now view your Streamlit app in your browser. + + URL: http://0.0.0.0:8501 +``` + +To view your app, users can browse to `http://0.0.0.0:8501` or `http://localhost:8501` + + + +Based on your server's network configuration, you could map to port 80/443 so that users can view your app using the server IP or hostname. For example: `http://your-server-ip:80` or `http://your-hostname:443`. + + diff --git a/data/deploy/tutorials/kubernetes.md b/data/deploy/tutorials/kubernetes.md new file mode 100644 index 0000000000000000000000000000000000000000..8c347dc391d1bbf5dfc90cbb3f76e9e240da4168 --- /dev/null +++ b/data/deploy/tutorials/kubernetes.md @@ -0,0 +1,296 @@ +--- +title: Deploy Streamlit using Kubernetes +slug: /deploy/tutorials/kubernetes +--- + +# Deploy Streamlit using Kubernetes + +## Introduction + +So you have an amazing app and you want to start sharing it with other people, what do you do? You have a few options. First, where do you want to run your Streamlit app, and how do you want to access it? + +- **On your corporate network** - Most corporate networks are closed to the outside world. You typically use a VPN to log onto your corporate network and access resources there. You could run your Streamlit app on a server in your corporate network for security reasons, to ensure that only folks internal to your company can access it. +- **On the cloud** - If you'd like to access your Streamlit app from outside of a corporate network, or share your app with folks outside of your home network or laptop, you might choose this option. In this case, it'll depend on your hosting provider. We have [community-submitted guides](/knowledge-base/deploy/deploy-streamlit-heroku-aws-google-cloud) from Heroku, AWS, and other providers. + +Wherever you decide to deploy your app, you will first need to containerize it. This guide walks you through using Kubernetes to deploy your app. If you prefer Docker see [Deploy Streamlit using Docker](/deploy/tutorials/docker). + +## Prerequisites + +1. [Install Docker Engine](#install-docker-engine) +2. [Install the gcloud CLI](#install-the-gcloud-cli) + +### Install Docker Engine + +If you haven't already done so, install [Docker](https://docs.docker.com/engine/install/#server) on your server. Docker provides `.deb` and `.rpm` packages from many Linux distributions, including: + +- [Debian](https://docs.docker.com/engine/install/debian/) +- [Ubuntu](https://docs.docker.com/engine/install/ubuntu/) + +Verify that Docker Engine is installed correctly by running the `hello-world` Docker image: + +```bash +sudo docker run hello-world +``` + + + +Follow Docker's official [post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/) to run Docker as a non-root user, so that you don't have to preface the `docker` command with `sudo`. + + + +### Install the gcloud CLI + +In this guide, we will orchestrate Docker containers with Kubernetes and host docker images on the Google Container Registry (GCR). As GCR is a Google-supported Docker registry, we need to register [`gcloud`](https://cloud.google.com/sdk/gcloud/reference) as the Docker credential helper. + +Follow the official documentation to [Install the gcloud CLI](https://cloud.google.com/sdk/docs/install) and initialize it. + +## Create a Docker container + +We need to create a docker container which contains all the dependencies and the application code. Below you can see the entrypoint, i.e. the command run when the container starts, and the Dockerfile definition. + +### Create an entrypoint script + +Create a `run.sh` script containing the following: + +```bash +#!/bin/bash + +APP_PID= +stopRunningProcess() { + # Based on https://linuxconfig.org/how-to-propagate-a-signal-to-child-processes-from-a-bash-script + if test ! "${APP_PID}" = '' && ps -p ${APP_PID} > /dev/null ; then + > /proc/1/fd/1 echo "Stopping ${COMMAND_PATH} which is running with process ID ${APP_PID}" + + kill -TERM ${APP_PID} + > /proc/1/fd/1 echo "Waiting for ${COMMAND_PATH} to process SIGTERM signal" + + wait ${APP_PID} + > /proc/1/fd/1 echo "All processes have stopped running" + else + > /proc/1/fd/1 echo "${COMMAND_PATH} was not started when the signal was sent or it has already been stopped" + fi +} + +trap stopRunningProcess EXIT TERM + +source ${VIRTUAL_ENV}/bin/activate + +streamlit run ${HOME}/app/streamlit_app.py & +APP_ID=${!} + +wait ${APP_ID} +``` + +### Create a Dockerfile + +Docker builds images by reading the instructions from a `Dockerfile`. A `Dockerfile` is a text document that contains all the commands a user could call on the command line to assemble an image. Learn more in the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/). The [docker build](https://docs.docker.com/engine/reference/commandline/build/) command builds an image from a `Dockerfile`. The [docker run](https://docs.docker.com/engine/reference/commandline/run/) command first creates a container over the specified image, and then starts it using the specified command. + +Here's an example `Dockerfile` that you can add to the root of your directory. + +```docker +FROM python:3.8-slim + +RUN groupadd --gid 1000 appuser \ + && useradd --uid 1000 --gid 1000 -ms /bin/bash appuser + +RUN pip3 install --no-cache-dir --upgrade \ + pip \ + virtualenv + +RUN apt-get update && apt-get install -y \ + build-essential \ + software-properties-common \ + git + +USER appuser +WORKDIR /home/appuser + +RUN git clone https://github.com/streamlit/streamlit-example.git app + +ENV VIRTUAL_ENV=/home/appuser/venv +RUN virtualenv ${VIRTUAL_ENV} +RUN . ${VIRTUAL_ENV}/bin/activate && pip install -r app/requirements.txt + +EXPOSE 8501 + +COPY run.sh /home/appuser +ENTRYPOINT ["./run.sh"] +``` + + + +As mentioned in [Development flow](/get-started/fundamentals/main-concepts#development-flow), for Streamlit version 1.10.0 and higher, Streamlit apps cannot be run from the root directory of Linux distributions. Your main script should live in a directory other than the root directory. If you try to run a Streamlit app from the root directory, Streamlit will throw a `FileNotFoundError: [Errno 2] No such file or directory` error. For more information, see GitHub issue [#5239](https://github.com/streamlit/streamlit/issues/5239). + +If you are using Streamlit version 1.10.0 or higher, you must set the `WORKDIR` to a directory other than the root directory. For example, you can set the `WORKDIR` to `/home/appuser` as shown in the example `Dockerfile` above. + + +### Build a Docker image + +Put the above files (`run.sh` and `Dockerfile`) in the same folder and build the docker image: + +```docker +docker build --platform linux/amd64 -t gcr.io/$GCP_PROJECT_ID/k8s-streamlit:test . +``` + + + +Replace `$GCP_PROJECT_ID` in the above command with the name of your Google Cloud project. + + + +### Upload the Docker image to a container registry + +The next step is to upload the Docker image to a container registry. In this example, we will use the [Google Container Registry (GCR)](https://cloud.google.com/container-registry). Start by enabling the Container Registry API. Sign in to Google Cloud and navigate to your project’s **Container Registry** and click **Enable**. + +We can now build the Docker image from the previous step and push it to our project’s GCR. Be sure to replace `$GCP_PROJECT_ID` in the docker push command with the name of your project: + +```bash +gcloud auth configure-docker +docker push gcr.io/$GCP_PROJECT_ID/k8s-streamlit:test +``` + +## Create a Kubernetes deployment + +For this step you will need a: + +- Running Kubernetes service +- Custom domain for which you can generate a TLS certificate +- DNS service where you can configure your custom domain to point to the application IP + +As the image was uploaded to the container registry in the previous step, we can run it in Kubernetes using the below configurations. + +### Install and run Kubernetes + +Make sure your [Kubernetes client](https://kubernetes.io/docs/tasks/tools/#kubectl), `kubectl`, is installed and running on your machine. + +### Configure a Google OAuth Client and oauth2-proxy + +For configuring the Google OAuth Client, please see [Google Auth Provider](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider#google-auth-provider). Configure oauth2-proxy to use the desired [OAuth Provider Configuration](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/oauth_provider) and update the oath2-proxy config in the config map. + +The below configuration contains a ouath2-proxy sidecar container which handles the authentication with Google. You can learn more from the [oauth2-proxy repository](https://github.com/oauth2-proxy/oauth2-proxy). + +### Create a Kubernetes configuration file + +Create a [YAML](https://yaml.org/) [configuration file](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#organizing-resource-configurations) named `k8s-streamlit.yaml`: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: streamlit-configmap +data: + oauth2-proxy.cfg: |- + http_address = "0.0.0.0:4180" + upstreams = ["http://127.0.0.1:8501/"] + email_domains = ["*"] + client_id = "" + client_secret = "" + cookie_secret = "<16, 24, or 32 bytes>" + redirect_url = + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: streamlit-deployment + labels: + app: streamlit +spec: + replicas: 1 + selector: + matchLabels: + app: streamlit + template: + metadata: + labels: + app: streamlit + spec: + containers: + - name: oauth2-proxy + image: quay.io/oauth2-proxy/oauth2-proxy:v7.2.0 + args: ["--config", "/etc/oauth2-proxy/oauth2-proxy.cfg"] + ports: + - containerPort: 4180 + livenessProbe: + httpGet: + path: /ping + port: 4180 + scheme: HTTP + readinessProbe: + httpGet: + path: /ping + port: 4180 + scheme: HTTP + volumeMounts: + - mountPath: "/etc/oauth2-proxy" + name: oauth2-config + - name: streamlit + image: gcr.io/GCP_PROJECT_ID/k8s-streamlit:test + imagePullPolicy: Always + ports: + - containerPort: 8501 + livenessProbe: + httpGet: + path: /_stcore/health + port: 8501 + scheme: HTTP + timeoutSeconds: 1 + readinessProbe: + httpGet: + path: /_stcore/health + port: 8501 + scheme: HTTP + timeoutSeconds: 1 + resources: + limits: + cpu: 1 + memory: 2Gi + requests: + cpu: 100m + memory: 745Mi + volumes: + - name: oauth2-config + configMap: + name: streamlit-configmap + +--- +apiVersion: v1 +kind: Service +metadata: + name: streamlit-service +spec: + type: LoadBalancer + selector: + app: streamlit + ports: + - name: streamlit-port + protocol: TCP + port: 80 + targetPort: 4180 +``` + + + +While the above configurations can be copied verbatim, you will have to configure the `oauth2-proxy` yourself and use the correct `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_ID`, `GCP_PROJECT_ID`, and `REDIRECT_URL`. + + + +Now create the configuration from the file in Kubernetes with the [`kubectl create`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#create) command: + +```bash +kubctl create -f k8s-streamlit.yaml +``` + +### Set up TLS support + +Since you are using the Google authentication, you will need to set up TLS support. Find out how in [TLS Configuration](https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/tls). + +### Verify the deployment + +Once the deployment and the service are created, we need to wait a couple of minutes for the public IP address to become available. We can check when that is ready by running: + +```bash +kubectl get service streamlit-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}' +``` + +After the public IP is assigned, you will need to configure in your DNS service an `A record` pointing to the above IP address. diff --git a/data/develop/_index.md b/data/develop/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..f8d342e41cc197a5a1e24cf19bdae86dc739d060 --- /dev/null +++ b/data/develop/_index.md @@ -0,0 +1,35 @@ +--- +title: Develop +slug: /develop +--- + +# Develop + +Get all the information you need to build beautiful, performant web apps with Streamlit! + + + Learn how Streamlit works with in-depth guides to our execution model and features. + Learn about our API with function definitions and examples. + Follow step-by-step instructions to build example apps and useful snippets. + Check out our quick references for easy access to convenient information like our changelog, cheat sheet, pre-release features, and roadmap. + diff --git a/data/develop/api-reference/_index.md b/data/develop/api-reference/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..6eb7ad43940dcf91ab467778065d767951df4893 --- /dev/null +++ b/data/develop/api-reference/_index.md @@ -0,0 +1,2701 @@ +--- +title: API Reference +slug: /develop/api-reference +--- + +# API reference + +Streamlit makes it easy for you to visualize, mutate, and share data. The API +reference is organized by activity type, like displaying data or optimizing +performance. Each section includes methods associated with the activity type, +including examples. + +Browse our API below and click to learn more about any of our available commands! 🎈 + +## Display almost anything + +### Write and magic + +
+ + + + + +

st.write

+ +Write arguments to the app. + +```python +st.write("Hello **world**!") +st.write(my_data_frame) +st.write(my_mpl_figure) +``` + +
+ + +

st.write_stream

+ +Write generators or streams to the app with a typewriter effect. + +```python +st.write_stream(my_generator) +st.write_stream(my_llm_stream) +``` + +
+ + +

Magic

+ +Any time Streamlit sees either a variable or literal value on its own line, it automatically writes that to your app using `st.write` + +```python +"Hello **world**!" +my_data_frame +my_mpl_figure +``` + +
+
+ +### Text elements + +
+ + + + +screenshot + +

Markdown

+ +Display string formatted as Markdown. + +```python +st.markdown("Hello **world**!") +``` + +
+ + +screenshot + +

Title

+ +Display text in title formatting. + +```python +st.title("The app title") +``` + +
+ + +screenshot + +

Header

+ +Display text in header formatting. + +```python +st.header("This is a header") +``` + +
+ + +screenshot + +

Subheader

+ +Display text in subheader formatting. + +```python +st.subheader("This is a subheader") +``` + +
+ + +screenshot + +

Caption

+ +Display text in small font. + +```python +st.caption("This is written small caption text") +``` + +
+ + +screenshot + +

Code block

+ +Display a code block with optional syntax highlighting. + +```python +st.code("a = 1234") +``` + +
+ + +screenshot + +

Echo

+ +Display some code in the app, then execute it. Useful for tutorials. + +```python +with st.echo(): + st.write('This code will be printed') +``` + +
+ + +screenshot + +

LaTeX

+ +Display mathematical expressions formatted as LaTeX. + +```python +st.latex("\int a x^2 \,dx") +``` + +
+ + +screenshot + +

Preformatted text

+ +Write fixed-width and preformatted text. + +```python +st.text("Hello world") +``` + +
+ + +screenshot + +

Divider

+ +Display a horizontal rule. + +```python +st.divider() +``` + +
+
+ + + + +screenshot + +

Annotated text

+ +Display annotated text in Streamlit apps. Created by [@tvst](https://github.com/tvst). + +```python +annotated_text("This ", ("is", "verb"), " some ", ("annotated", "adj"), ("text", "noun"), " for those of ", ("you", "pronoun"), " who ", ("like", "verb"), " this sort of ", ("thing", "noun"), ".") +``` + +
+ + + +screenshot + +

Drawable Canvas

+ +Provides a sketching canvas using [Fabric.js](http://fabricjs.com/). Created by [@andfanilo](https://github.com/andfanilo). + +```python +st_canvas(fill_color="rgba(255, 165, 0, 0.3)", stroke_width=stroke_width, stroke_color=stroke_color, background_color=bg_color, background_image=Image.open(bg_image) if bg_image else None, update_streamlit=realtime_update, height=150, drawing_mode=drawing_mode, point_display_radius=point_display_radius if drawing_mode == 'point' else 0, key="canvas",) +``` + +
+ + + +screenshot + +

Tags

+ +Add tags to your Streamlit apps. Created by [@gagan3012](https://github.com/gagan3012). + +```python +st_tags(label='# Enter Keywords:', text='Press enter to add more', value=['Zero', 'One', 'Two'], suggestions=['five', 'six', 'seven', 'eight', 'nine', 'three', 'eleven', 'ten', 'four'], maxtags = 4, key='1') +``` + +
+ + + +screenshot + +

NLU

+ +Apply text mining on a dataframe. Created by [@JohnSnowLabs](https://github.com/JohnSnowLabs/). + +```python +nlu.load('sentiment').predict('I love NLU! <3') +``` + +
+ + + +screenshot + +

Streamlit Extras

+ +A library with useful Streamlit extras. Created by [@arnaudmiribel](https://github.com/arnaudmiribel/). + +```python +mention(label="An awesome Streamlit App", icon="streamlit", url="https://extras.streamlit.app",) +``` + +
+
+ +### Data elements + +
+ + + +screenshot + +

Dataframes

+ +Display a dataframe as an interactive table. + +```python +st.dataframe(my_data_frame) +``` + +
+ + +screenshot + +

Data editor

+ +Display a data editor widget. + +```python +edited = st.data_editor(df, num_rows="dynamic") +``` + +
+ + +screenshot + +

Column configuration

+ +Configure the display and editing behavior of dataframes and data editors. + +```python +st.column_config.NumberColumn("Price (in USD)", min_value=0, format="$%d") +``` + +
+ + +screenshot + +

Static tables

+ +Display a static table. + +```python +st.table(my_data_frame) +``` + +
+ +screenshot + +

Metrics

+ +Display a metric in big bold font, with an optional indicator of how the metric changed. + +```python +st.metric("My metric", 42, 2) +``` + +
+ +screenshot + +

Dicts and JSON

+ +Display object or string as a pretty-printed JSON string. + +```python +st.json(my_dict) +``` + +
+
+ + + + + +screenshot + +

Streamlit Aggrid

+ +Implementation of Ag-Grid component for Streamlit. Created by [@PablocFonseca](https://github.com/PablocFonseca). + +```python +df = pd.DataFrame({'col1': [1, 2, 3], 'col2': [4, 5, 6]}) +grid_return = AgGrid(df, editable=True) + +new_df = grid_return['data'] +``` + +
+ + + +screenshot + +

Streamlit Folium

+ +Streamlit Component for rendering Folium maps. Created by [@randyzwitch](https://github.com/randyzwitch). + +```python +m = folium.Map(location=[39.949610, -75.150282], zoom_start=16) +folium.Marker([39.949610, -75.150282], popup="Liberty Bell", tooltip="Liberty Bell").add_to(m) + +st_data = st_folium(m, width=725) +``` + +
+ + + +screenshot + +

Pandas Profiling

+ +Pandas profiling component for Streamlit. Created by [@okld](https://github.com/okld/). + +```python +df = pd.read_csv("https://storage.googleapis.com/tf-datasets/titanic/train.csv") +pr = df.profile_report() + +st_profile_report(pr) +``` + +
+ + + +screenshot + +

Image Coordinates

+ +Get the coordinates of clicks on an image. Created by [@blackary](https://github.com/blackary/). + +```python +from streamlit_image_coordinates import streamlit_image_coordinates +value = streamlit_image_coordinates("https://placekitten.com/200/300") + +st.write(value) +``` + +
+ + + +screenshot + +

Plotly Events

+ +Make Plotly charts interactive!. Created by [@null-jones](https://github.com/null-jones/). + +```python +from streamlit_plotly_events import plotly_events +fig = px.line(x=[1], y=[1]) + +selected_points = plotly_events(fig) +``` + +
+ + + +screenshot + +

Streamlit Extras

+ +A library with useful Streamlit extras. Created by [@arnaudmiribel](https://github.com/arnaudmiribel/). + +```python +from streamlit_extras.metric_cards import style_metric_cards +col3.metric(label="No Change", value=5000, delta=0) + +style_metric_cards() +``` + +
+ +
+ +### Chart elements + +
+ + + + +screenshot + +

Simple area charts

+ +Display an area chart. + +```python +st.area_chart(my_data_frame) +``` + +
+ +screenshot + +

Simple bar charts

+ +Display a bar chart. + +```python +st.bar_chart(my_data_frame) +``` + +
+ +screenshot + +

Simple line charts

+ +Display a line chart. + +```python +st.line_chart(my_data_frame) +``` + +
+ +screenshot + +

Simple scatter charts

+ +Display a line chart. + +```python +st.scatter_chart(my_data_frame) +``` + +
+ +screenshot + +

Scatterplots on maps

+ +Display a map with points on it. + +```python +st.map(my_data_frame) +``` + +
+ +screenshot + +

Matplotlib

+ +Display a matplotlib.pyplot figure. + +```python +st.pyplot(my_mpl_figure) +``` + +
+ +screenshot + +

Altair

+ +Display a chart using the Altair library. + +```python +st.altair_chart(my_altair_chart) +``` + +
+ +screenshot + +

Vega-Lite

+ +Display a chart using the Vega-Lite library. + +```python +st.vega_lite_chart(my_vega_lite_chart) +``` + +
+ +screenshot + +

Plotly

+ +Display an interactive Plotly chart. + +```python +st.plotly_chart(my_plotly_chart) +``` + +
+ +screenshot + +

Bokeh

+ +Display an interactive Bokeh chart. + +```python +st.bokeh_chart(my_bokeh_chart) +``` + +
+ +screenshot + +

PyDeck

+ +Display a chart using the PyDeck library. + +```python +st.pydeck_chart(my_pydeck_chart) +``` + +
+ +screenshot + +

GraphViz

+ +Display a graph using the dagre-d3 library. + +```python +st.graphviz_chart(my_graphviz_spec) +``` + +
+
+ + + + + +screenshot + +

Plost

+ +A deceptively simple plotting library for Streamlit. Created by [@tvst](https://github.com/tvst). + +```python +import plost +plost.line_chart(my_dataframe, x='time', y='stock_value', color='stock_name',) +``` + +
+ + + +screenshot + +

HiPlot

+ +High dimensional Interactive Plotting. Created by [@facebookresearch](https://github.com/facebookresearch). + +```python +data = [{'dropout':0.1, 'lr': 0.001, 'loss': 10.0, 'optimizer': 'SGD'}, {'dropout':0.15, 'lr': 0.01, 'loss': 3.5, 'optimizer': 'Adam'}, {'dropout':0.3, 'lr': 0.1, 'loss': 4.5, 'optimizer': 'Adam'}] +hip.Experiment.from_iterable(data).display() +``` + +
+ + + +screenshot + +

ECharts

+ +High dimensional Interactive Plotting. Created by [@andfanilo](https://github.com/andfanilo). + +```python +from streamlit_echarts import st_echarts +st_echarts(options=options) +``` + +
+ + + +screenshot + +

Streamlit Folium

+ +Streamlit Component for rendering Folium maps. Created by [@randyzwitch](https://github.com/randyzwitch). + +```python +m = folium.Map(location=[39.949610, -75.150282], zoom_start=16) +st_data = st_folium(m, width=725) +``` + +
+ + + +screenshot + +

Spacy-Streamlit

+ +spaCy building blocks and visualizers for Streamlit apps. Created by [@explosion](https://github.com/explosion). + +```python +models = ["en_core_web_sm", "en_core_web_md"] +spacy_streamlit.visualize(models, "Sundar Pichai is the CEO of Google.") +``` + +
+ + + +screenshot + +

Streamlit Agraph

+ +A Streamlit Graph Vis, based on [react-grah-vis](https://github.com/crubier/react-graph-vis). Created by [@ChrisDelClea](https://github.com/ChrisDelClea). + +```python +from streamlit_agraph import agraph, Node, Edge, Config +agraph(nodes=nodes, edges=edges, config=config) +``` + +
+ + + +screenshot + +

Streamlit Lottie

+ +Integrate [Lottie](https://lottiefiles.com/) animations inside your Streamlit app. Created by [@andfanilo](https://github.com/andfanilo). + +```python +lottie_hello = load_lottieurl("https://assets5.lottiefiles.com/packages/lf20_V9t630.json") +st_lottie(lottie_hello, key="hello") +``` + +
+ + + +screenshot + +

Plotly Events

+ +Make Plotly charts interactive!. Created by [@null-jones](https://github.com/null-jones/). + +```python +fig = px.line(x=[1], y=[1]) +selected_points = plotly_events(fig) +``` + +
+ + + +screenshot + +

Streamlit Extras

+ +A library with useful Streamlit extras. Created by [@arnaudmiribel](https://github.com/arnaudmiribel/). + +```python +chart += get_annotations_chart(annotations=[("Mar 01, 2008", "Pretty good day for GOOG"), ("Dec 01, 2007", "Something's going wrong for GOOG & AAPL"), ("Nov 01, 2008", "Market starts again thanks to..."), ("Dec 01, 2009", "Small crash for GOOG after..."),],) +st.altair_chart(chart, use_container_width=True) +``` + +
+ +
+ +### Input widgets + +
+ + + + +screenshot + +

Button

+ +Display a button widget. + +```python +clicked = st.button("Click me") +``` + +
+ + +screenshot + +

Download button

+ +Display a download button widget. + +```python +st.download_button("Download file", file) +``` + +
+ + +screenshot + +

Form button

+ +Display a form submit button. For use with `st.form`. + +```python +st.form_submit_button("Sign up") +``` + +
+ + +screenshot + +

Link button

+ +Display a link button. + +```python +st.link_button("Go to gallery", url) +``` + +
+ + +screenshot + +

Page link

+ +Display a link to another page in a multipage app. + +```python +st.page_link("app.py", label="Home", icon="🏠") +st.page_link("pages/profile.py", label="My profile") +``` + +
+ + +screenshot + +

Checkbox

+ +Display a checkbox widget. + +```python +selected = st.checkbox("I agree") +``` + +
+ + +screenshot + +

Color picker

+ +Display a color picker widget. + +```python +color = st.color_picker("Pick a color") +``` + +
+ + +screenshot + +

Multiselect

+ +Display a multiselect widget. The multiselect widget starts as empty. + +```python +choices = st.multiselect("Buy", ["milk", "apples", "potatoes"]) +``` + +
+ + +screenshot + +

Radio

+ +Display a radio button widget. + +```python +choice = st.radio("Pick one", ["cats", "dogs"]) +``` + +
+ + +screenshot + +

Selectbox

+ +Display a select widget. + +```python +choice = st.selectbox("Pick one", ["cats", "dogs"]) +``` + +
+ + +screenshot + +

Select-slider

+ +Display a slider widget to select items from a list. + +```python +size = st.select_slider("Pick a size", ["S", "M", "L"]) +``` + +
+ + +screenshot + +

Toggle

+ +Display a toggle widget. + +```python +activated = st.toggle("Activate") +``` + +
+ + +screenshot + +

Number input

+ +Display a numeric input widget. + +```python +choice = st.number_input("Pick a number", 0, 10) +``` + +
+ + +screenshot + +

Slider

+ +Display a slider widget. + +```python +number = st.slider("Pick a number", 0, 100) +``` + +
+ + +screenshot + +

Date input

+ +Display a date input widget. + +```python +date = st.date_input("Your birthday") +``` + +
+ + +screenshot + +

Time input

+ +Display a time input widget. + +```python +time = st.time_input("Meeting time") +``` + +
+ + +screenshot + +

Chat input

+ +Display a chat input widget. + +```python +prompt = st.chat_input("Say something") +if prompt: + st.write(f"The user has sent: {prompt}") +``` + +
+ + +screenshot + +

Text-area

+ +Display a multi-line text input widget. + +```python +text = st.text_area("Text to translate") +``` + +
+ + +screenshot + +

Text input

+ +Display a single-line text input widget. + +```python +name = st.text_input("First name") +``` + +
+ + +screenshot + +

Data editor

+ +Display a data editor widget. + +```python +edited = st.experimental_data_editor(df, num_rows="dynamic") +``` + +
+ + +screenshot + +

File Uploader

+ +Display a file uploader widget. + +```python +data = st.file_uploader("Upload a CSV") +``` + +
+ + +screenshot + +

Camera input

+ +Display a widget that allows users to upload images directly from a camera. + +```python +image = st.camera_input("Take a picture") +``` + +
+
+ + + + + +screenshot + +

Streamlit Elements

+ +Create a draggable and resizable dashboard in Streamlit. Created by [@okls](https://github.com/okls). + +```python +from streamlit_elements import elements, mui, html + +with elements("new_element"): + mui.Typography("Hello world") +``` + +
+ + + +screenshot + +

Tags

+ +Add tags to your Streamlit apps. Created by [@gagan3012](https://github.com/gagan3012). + +```python +from streamlit_tags import st_tags + +st_tags(label='# Enter Keywords:', text='Press enter to add more', value=['Zero', 'One', 'Two'], +suggestions=['five', 'six', 'seven', 'eight', 'nine', 'three', 'eleven', 'ten', 'four'], maxtags = 4, key='1') +``` + +
+ + + +screenshot + +

Stqdm

+ +The simplest way to handle a progress bar in streamlit app. Created by [@Wirg](https://github.com/Wirg). + +```python +from stqdm import stqdm + +for _ in stqdm(range(50)): + sleep(0.5) +``` + +
+ + + +screenshot + +

Timeline

+ +Display a Timeline in Streamlit apps using [TimelineJS](https://timeline.knightlab.com/). Created by [@innerdoc](https://github.com/innerdoc). + +```python +from streamlit_timeline import timeline + +with open('example.json', "r") as f: + timeline(f.read(), height=800) +``` + +
+ + + +screenshot + +

Camera input live

+ +Alternative for st.camera_input which returns the webcam images live. Created by [@blackary](https://github.com/blackary). + +```python +from camera_input_live import camera_input_live + +image = camera_input_live() +st.image(value) +``` + +
+ + + +screenshot + +

Streamlit Ace

+ +Ace editor component for Streamlit. Created by [@okld](https://github.com/okld). + +```python +from streamlit_ace import st_ace + +content = st_ace() +content +``` + +
+ + + +screenshot + +

Streamlit Chat

+ +Streamlit Component for a Chatbot UI. Created by [@AI-Yash](https://github.com/AI-Yash). + +```python +from streamlit_chat import message + +message("My message") +message("Hello bot!", is_user=True) # align's the message to the right +``` + +
+ + + +screenshot + +

Streamlit Option Menu

+ +Select a single item from a list of options in a menu. Created by [@victoryhb](https://github.com/victoryhb). + +```python +from streamlit_option_menu import option_menu + +option_menu("Main Menu", ["Home", 'Settings'], + icons=['house', 'gear'], menu_icon="cast", default_index=1) +``` + +
+ + + +screenshot + +

Streamlit Extras

+ +A library with useful Streamlit extras. Created by [@arnaudmiribel](https://github.com/arnaudmiribel/). + +```python +from streamlit_extras.stoggle import stoggle + +stoggle( + "Click me!", """🥷 Surprise! Here's some additional content""",) +``` + +
+ +
+ +### Media elements + +
+ + + + +screenshot + +

Image

+ +Display an image or list of images. + +```python +st.image(numpy_array) +st.image(image_bytes) +st.image(file) +st.image("https://example.com/myimage.jpg") +``` + +
+ + +screenshot + +

Audio

+ +Display an audio player. + +```python +st.audio(numpy_array) +st.audio(audio_bytes) +st.audio(file) +st.audio("https://example.com/myaudio.mp3", format="audio/mp3") +``` + +
+ + +screenshot + +

Video

+ +Display a video player. + +```python +st.video(numpy_array) +st.video(video_bytes) +st.video(file) +st.video("https://example.com/myvideo.mp4", format="video/mp4") +``` + +
+
+ + + + + +screenshot + +

Streamlit Webrtc

+ +Handling and transmitting real-time video/audio streams with Streamlit. Created by [@whitphx](https://github.com/whitphx). + +```python +from streamlit_webrtc import webrtc_streamer + +webrtc_streamer(key="sample") +``` + +
+ + + +screenshot + +

Drawable Canvas

+ +Provides a sketching canvas using [Fabric.js](http://fabricjs.com/). Created by [@andfanilo](https://github.com/andfanilo). + +```python +from streamlit_drawable_canvas import st_canvas + +st_canvas(fill_color="rgba(255, 165, 0, 0.3)", stroke_width=stroke_width, stroke_color=stroke_color, background_color=bg_color, background_image=Image.open(bg_image) if bg_image else None, update_streamlit=realtime_update, height=150, drawing_mode=drawing_mode, point_display_radius=point_display_radius if drawing_mode == 'point' else 0, key="canvas",) +``` + +
+ + + +screenshot + +

Image Comparison

+ +Compare images with a slider using [JuxtaposeJS](https://juxtapose.knightlab.com/). Created by [@fcakyon](https://github.com/fcakyon). + +```python +from streamlit_image_comparison import image_comparison + +image_comparison(img1="image1.jpg", img2="image2.jpg",) +``` + +
+ + + +screenshot + +

Streamlit Cropper

+ +A simple image cropper for Streamlit. Created by [@turner-anderson](https://github.com/turner-anderson). + +```python +from streamlit_cropper import st_cropper + +st_cropper(img, realtime_update=realtime_update, box_color=box_color, aspect_ratio=aspect_ratio) +``` + +
+ + + +screenshot + +

Image Coordinates

+ +Get the coordinates of clicks on an image. Created by [@blackary](https://github.com/blackary/). + +```python +from streamlit_image_coordinates import streamlit_image_coordinates + +streamlit_image_coordinates("https://placekitten.com/200/300") +``` + +
+ + + +screenshot + +

Streamlit Lottie

+ +Integrate [Lottie](https://lottiefiles.com/) animations inside your Streamlit app. Created by [@andfanilo](https://github.com/andfanilo). + +```python +lottie_hello = load_lottieurl("https://assets5.lottiefiles.com/packages/lf20_V9t630.json") + +st_lottie(lottie_hello, key="hello") +``` + +
+ +
+ +### Layouts and containers + +
+ + + + +screenshot + +

Columns

+ +Insert containers laid out as side-by-side columns. + +```python +col1, col2 = st.columns(2) +col1.write("this is column 1") +col2.write("this is column 2") +``` + +
+ + +screenshot + +

Container

+ +Insert a multi-element container. + +```python +c = st.container() +st.write("This will show last") +c.write("This will show first") +c.write("This will show second") +``` + +
+ + +screenshot + +

Modal dialogs

+ +Insert a modal dialog that can rerun independently from the rest of the script. + +```python +@st.experimental_dialog() +def email_form(): + name = st.text_input("Name") + email = st.text_input("Email") +``` + +
+ + +screenshot + +

Empty

+ +Insert a single-element container. + +```python +c = st.empty() +st.write("This will show last") +c.write("This will be replaced") +c.write("This will show first") +``` + +
+ + +screenshot + +

Expander

+ +Insert a multi-element container that can be expanded/collapsed. + +```python +with st.expander("Open to see more"): + st.write("This is more content") +``` + +
+ + +screenshot + +

Popover

+ +Insert a multi-element popover container that can be opened/closed. + +```python +with st.popover("Settings"): + st.checkbox("Show completed") +``` + +
+ + +screenshot + +

Sidebar

+ +Display items in a sidebar. + +```python +st.sidebar.write("This lives in the sidebar") +st.sidebar.button("Click me!") +``` + +
+ + +screenshot + +

Tabs

+ +Insert containers separated into tabs. + +```python +tab1, tab2 = st.tabs(["Tab 1", "Tab2"]) +tab1.write("this is tab 1") +tab2.write("this is tab 2") +``` + +
+
+ + + + + +screenshot + +

Streamlit Elements

+ +Create a draggable and resizable dashboard in Streamlit. Created by [@okls](https://github.com/okls). + +```python +from streamlit_elements import elements, mui, html + +with elements("new_element"): + mui.Typography("Hello world") +``` + +
+ + + +screenshot + +

Pydantic

+ +Auto-generate Streamlit UI from Pydantic Models and Dataclasses. Created by [@lukasmasuch](https://github.com/lukasmasuch). + +```python +import streamlit_pydantic as sp + +sp.pydantic_form(key="my_form", + model=ExampleModel) +``` + +
+ + + +screenshot + +

Streamlit Pages

+ +An experimental version of Streamlit Multi-Page Apps. Created by [@blackary](https://github.com/blackary). + +```python +from st_pages import Page, show_pages, add_page_title + +show_pages([ Page("streamlit_app.py", "Home", "🏠"), + Page("other_pages/page2.py", "Page 2", ":books:"), ]) +``` + +
+ +
+ +### Chat elements + +
+ +Streamlit provides a few commands to help you build conversational apps. These chat elements are designed to be used in conjunction with each other, but you can also use them separately. + +`st.chat_message` lets you insert a chat message container into the app so you can display messages from the user or the app. Chat containers can contain other Streamlit elements, including charts, tables, text, and more. `st.chat_input` lets you display a chat input widget so the user can type in a message. + + + + +screenshot + +

Chat input

+ +Display a chat input widget. + +```python +prompt = st.chat_input("Say something") +if prompt: + st.write(f"The user has sent: {prompt}") +``` + +
+ + +screenshot + +

Chat message

+ +Insert a chat message container. + +```python +import numpy as np +with st.chat_message("user"): + st.write("Hello 👋") + st.line_chart(np.random.randn(30, 3)) +``` + +
+ + +screenshot + +

Status container

+ +Display output of long-running tasks in a container. + +```python +with st.status('Running'): + do_something_slow() +``` + +
+ + +

st.write_stream

+ +Write generators or streams to the app with a typewriter effect. + +```python +st.write_stream(my_generator) +st.write_stream(my_llm_stream) +``` + +
+
+ +### Status elements + +
+ + + + +screenshot + +

Progress bar

+ +Display a progress bar. + +```python +for i in range(101): + st.progress(i) + do_something_slow() +``` + +
+ + +screenshot + +

Spinner

+ +Temporarily displays a message while executing a block of code. + +```python +with st.spinner("Please wait..."): + do_something_slow() +``` + +
+ + +screenshot + +

Status container

+ +Display output of long-running tasks in a container. + +```python +with st.status('Running'): + do_something_slow() +``` + +
+ + +screenshot + +

Toast

+ +Briefly displays a toast message in the bottom-right corner. + +```python +st.toast('Butter!', icon='🧈') +``` + +
+ + +screenshot + +

Balloons

+ +Display celebratory balloons! + +```python +do_something() + +# Celebrate when all done! +st.balloons() +``` + +
+ + +screenshot + +

Snowflakes

+ +Display celebratory snowflakes! + +```python +do_something() + +# Celebrate when all done! +st.snow() +``` + +
+ + +screenshot + +

Success box

+ +Display a success message. + +```python +st.success("Match found!") +``` + +
+ + +screenshot + +

Info box

+ +Display an informational message. + +```python +st.info("Dataset is updated every day at midnight.") +``` + +
+ + +screenshot + +

Warning box

+ +Display warning message. + +```python +st.warning("Unable to fetch image. Skipping...") +``` + +
+ + +screenshot + +

Error box

+ +Display error message. + +```python +st.error("We encountered an error") +``` + +
+ + +screenshot + +

Exception output

+ +Display an exception. + +```python +e = RuntimeError("This is an exception of type RuntimeError") +st.exception(e) +``` + +
+ +
+ + + + + +screenshot + +

Stqdm

+ +The simplest way to handle a progress bar in streamlit app. Created by [@Wirg](https://github.com/Wirg). + +```python +from stqdm import stqdm + +for _ in stqdm(range(50)): + sleep(0.5) +``` + +
+ + + +screenshot + +

Custom notification box

+ +A custom notification box with the ability to close it out. Created by [@Socvest](https://github.com/Socvest). + +```python +from streamlit_custom_notification_box import custom_notification_box + +styles = {'material-icons':{'color': 'red'}, 'text-icon-link-close-container': {'box-shadow': '#3896de 0px 4px'}, 'notification-text': {'':''}, 'close-button':{'':''}, 'link':{'':''}} +custom_notification_box(icon='info', textDisplay='We are almost done with your registration...', externalLink='more info', url='#', styles=styles, key="foo") +``` + +
+ + + +screenshot + +

Streamlit Extras

+ +A library with useful Streamlit extras. Created by [@arnaudmiribel](https://github.com/arnaudmiribel/). + +```python +from streamlit_extras.let_it_rain import rain + +rain(emoji="🎈", font_size=54, + falling_speed=5, animation_length="infinite",) +``` + +
+ +
+ +## App logic and configuration + +### Navigation and pages + +
+ + + + + +

Switch page

+ +Programmatically navigates to a specified page. + +```python +st.switch_page("pages/my_page.py") +``` + +
+ + + +screenshot + +

Page link

+ +Display a link to another page in a multipage app. + +```python +st.page_link("app.py", label="Home", icon="🏠") +st.page_link("pages/profile.py", label="My profile") +``` + +
+ +
+ +### Execution flow + +
+ + + + +screenshot + +

Modal dialogs

+ +Insert a modal dialog that can rerun independently from the rest of the script. + +```python +@st.experimental_dialog() +def email_form(): + name = st.text_input("Name") + email = st.text_input("Email") +``` + +
+ + +

Forms

+ +Create a form that batches elements together with a “Submit" button. + +```python +with st.form(key='my_form'): + name = st.text_input("Name") + email = st.text_input("Email") + st.form_submit_button("Sign up") +``` + +
+ + +

Partial reruns

+ +Define a fragment to rerun independently from the rest of the script. + +```python +@st.experimental_fragment(run_every="10s") +def fragment(): + df = get_data() + st.line_chart(df) +``` + +
+ + +

Rerun script

+ +Rerun the script immediately. + +```python +st.rerun() +``` + +
+ + +

Stop execution

+ +Stops execution immediately. + +```python +st.stop() +``` + +
+
+ + + + + +screenshot + +

Autorefresh

+ +Force a refresh without tying up a script. Created by [@kmcgrady](https://github.com/kmcgrady). + +```python +from streamlit_autorefresh import st_autorefresh + +st_autorefresh(interval=2000, limit=100, + key="fizzbuzzcounter") +``` + +
+ + + +screenshot + +

Pydantic

+ +Auto-generate Streamlit UI from Pydantic Models and Dataclasses. Created by [@lukasmasuch](https://github.com/lukasmasuch). + +```python +import streamlit_pydantic as sp + +sp.pydantic_form(key="my_form", + model=ExampleModel) +``` + +
+ + + +screenshot + +

Streamlit Pages

+ +An experimental version of Streamlit Multi-Page Apps. Created by [@blackary](https://github.com/blackary). + +```python +from st_pages import Page, show_pages, add_page_title + +show_pages([ Page("streamlit_app.py", "Home", "🏠"), + Page("other_pages/page2.py", "Page 2", ":books:"), ]) +``` + +
+ +
+ +### Caching and state + +
+ + + + +

Cache data

+ +Function decorator to cache functions that return data (e.g. dataframe transforms, database queries, ML inference). + +```python +@st.cache_data +def long_function(param1, param2): + # Perform expensive computation here or + # fetch data from the web here + return data +``` + +
+ + + +

Cache resource

+ +Function decorator to cache functions that return global resources (e.g. database connections, ML models). + +```python +@st.cache_resource +def init_model(): + # Return a global resource here + return pipeline( + "sentiment-analysis", + model="distilbert-base-uncased-finetuned-sst-2-english" + ) +``` + +
+ + + +

Session state

+ +Session state is a way to share variables between reruns, for each user session. + +```python +st.session_state['key'] = value +``` + +
+ + + +

Query parameters

+ +Get, set, or clear the query parameters that are shown in the browser's URL bar. + +```python +st.query_params[key] = value +st.query_params.clear() +``` + +
+ +
+ +### Connections and databases + +#### Setup your connection + + + + +screenshot + +

Create a connection

+ +Connect to a data source or API + +```python +conn = st.connection('pets_db', type='sql') +pet_owners = conn.query('select * from pet_owners') +st.dataframe(pet_owners) +``` + +
+
+ +#### Built-in connections + + + + + +screenshot + +

SnowflakeConnection

+ +A connection to Snowflake. + +```python +conn = st.connection('snowflake') +``` + +
+ + + +screenshot + +

SQLConnection

+ +A connection to a SQL database using SQLAlchemy. + +```python +conn = st.connection('sql') +``` + +
+
+ +#### Build your own connections + + + + +

Connection base class

+ +Build your own connection with `BaseConnection`. + +```python +class MyConnection(BaseConnection[myconn.MyConnection]): + def _connect(self, **kwargs) -> MyConnection: + return myconn.connect(**self._secrets, **kwargs) + def query(self, query): + return self._instance.query(query) +``` + +
+ +
+ +#### Secrets management + + + + + +

Secrets singleton

+ +Access secrets from a local TOML file. + +```python +key = st.secrets["OpenAI_key"] +``` + +
+ + +

Secrets file

+ +Save your secrets in a per-project or per-profile TOML file. + +```python +OpenAI_key = "" +``` + +
+ +
+ + + + + +screenshot + +

Authenticator

+ +A secure authentication module to validate user credentials. Created by [@mkhorasani](https://github.com/mkhorasani). + +```python +import streamlit_authenticator as stauth + +authenticator = stauth.Authenticate( config['credentials'], config['cookie']['name'], +config['cookie']['key'], config['cookie']['expiry_days'], config['preauthorized']) +``` + +
+ + + +screenshot + +

WS localStorage

+ +A simple synchronous way of accessing localStorage from your app. Created by [@gagangoku](https://github.com/gagangoku). + +```python +from streamlit_ws_localstorage import injectWebsocketCode + +ret = conn.setLocalStorageVal(key='k1', val='v1') +st.write('ret: ' + ret) +``` + +
+ + + +screenshot + +

Streamlit Auth0

+ +The fastest way to provide comprehensive login inside Streamlit. Created by [@conradbez](https://github.com/conradbez). + +```python +from auth0_component import login_button + +user_info = login_button(clientId, domain = domain) +st.write(user_info) +``` + +
+ +
+ +### Custom Components + +
+ + + + + +

Declare a component

+ +Create and register a custom component. + +```python +st.components.v1.declare_component( + "custom_slider", + "/frontend", +) +``` + +
+ + + +

HTML

+ +Display an HTML string in an iframe. + +```python +st.components.v1.html( + "

Foo bar.

" +) +``` + +
+ + + +

iframe

+ +Load a remote URL in an iframe. + +```python +st.components.v1.iframe( + "docs.streamlit.io" +) +``` + +
+ +
+ +### Utilities and user info + +
+ + + + +

User info

+ +`st.experimental_user` returns information about the logged-in user of private apps on Streamlit Community Cloud. + +```python +if st.experimental_user.email == "foo@corp.com": + st.write("Welcome back, ", st.experimental_user.email) +else: + st.write("You are not authorized to view this page.") +``` + +
+ + +

Get help

+ +Display object’s doc string, nicely formatted. + +```python +st.help(st.write) +st.help(pd.DataFrame) +``` + +
+ + +

Render HTML

+ +Renders HTML strings to your app. + +```python +css = """ + +""" +st.html(css) +``` + +
+
+ +### Configuration + +
+ + + + +

Configuration file

+ +Configures the default settings for your app. + +``` +your-project/ +├── .streamlit/ +│ └── config.toml +└── your_app.py +``` + +
+ + +

Set page title, favicon, and more

+ +Configures the default settings of the page. + +```python +st.set_page_config( + page_title="My app", + page_icon=":shark:", +) +``` + +
+
+ +## Developer tools + +### App testing + +
+ + + + + +

st.testing.v1.AppTest

+ +`st.testing.v1.AppTest` simulates a running Streamlit app for testing. + +```python +from streamlit.testing.v1 import AppTest + +at = AppTest.from_file("streamlit_app.py") +at.secrets["WORD"] = "Foobar" +at.run() +assert not at.exception + +at.text_input("word").input("Bazbat").run() +assert at.warning[0].value == "Try again." +``` + +
+ + + +

AppTest.from_file

+ +`st.testing.v1.AppTest.from_file` initializes a simulated app from a file. + +```python +from streamlit.testing.v1 import AppTest + +at = AppTest.from_file("streamlit_app.py") +at.run() +``` + +
+ + + +

AppTest.from_string

+ +`st.testing.v1.AppTest.from_string` initializes a simulated app from a string. + +```python +from streamlit.testing.v1 import AppTest + +at = AppTest.from_string(app_script_as_string) +at.run() +``` + +
+ + + +

AppTest.from_function

+ +`st.testing.v1.AppTest.from_function` initializes a simulated app from a function. + +```python +from streamlit.testing.v1 import AppTest + +at = AppTest.from_function(app_script_as_callable) +at.run() +``` + +
+ + + +

Block

+ +A representation of container elements, including: + +- `st.chat_message` +- `st.columns` +- `st.sidebar` +- `st.tabs` +- The main body of the app. + +```python +# at.sidebar returns a Block +at.sidebar.button[0].click().run() +assert not at.exception +``` + +
+ + + +

Element

+ +The base class for representation of all elements, including: + +- `st.title` +- `st.header` +- `st.markdown` +- `st.dataframe` + +```python +# at.title returns a sequence of Title +# Title inherits from Element +assert at.title[0].value == "My awesome app" +``` + +
+ + + +

Button

+ +A representation of `st.button` and `st.form_submit_button`. + +```python +at.button[0].click().run() +``` + +
+ + + +

ChatInput

+ +A representation of `st.chat_input`. + +```python +at.chat_input[0].set_value("What is Streamlit?").run() +``` + +
+ + + +

Checkbox

+ +A representation of `st.checkbox`. + +```python +at.checkbox[0].check().run() +``` + +
+ + + +

ColorPicker

+ +A representation of `st.color_picker`. + +```python +at.color_picker[0].pick("#FF4B4B").run() +``` + +
+ + + +

DateInput

+ +A representation of `st.date_input`. + +```python +release_date = datetime.date(2023, 10, 26) +at.date_input[0].set_value(release_date).run() +``` + +
+ + + +

Multiselect

+ +A representation of `st.multiselect`. + +```python +at.multiselect[0].select("New York").run() +``` + +
+ + + +

NumberInput

+ +A representation of `st.number_input`. + +```python +at.number_input[0].increment().run() +``` + +
+ + + +

Radio

+ +A representation of `st.radio`. + +```python +at.radio[0].set_value("New York").run() +``` + +
+ + + +

SelectSlider

+ +A representation of `st.select_slider`. + +```python +at.select_slider[0].set_range("A","C").run() +``` + +
+ + + +

Selectbox

+ +A representation of `st.selectbox`. + +```python +at.selectbox[0].select("New York").run() +``` + +
+ + + +

Slider

+ +A representation of `st.slider`. + +```python +at.slider[0].set_range(2,5).run() +``` + +
+ + + +

TextArea

+ +A representation of `st.text_area`. + +```python +at.text_area[0].input("Streamlit is awesome!").run() +``` + +
+ + + +

TextInput

+ +A representation of `st.text_input`. + +```python +at.text_input[0].input("Streamlit").run() +``` + +
+ + + +

TimeInput

+ +A representation of `st.time_input`. + +```python +at.time_input[0].increment().run() +``` + +
+ + + +

Toggle

+ +A representation of `st.toggle`. + +```python +at.toggle[0].set_value("True").run() +``` + +
+ +
+ + + + + +screenshot + +

Pandas Profiling

+ +Pandas profiling component for Streamlit. Created by [@okld](https://github.com/okld/). + +```python +df = pd.read_csv("https://storage.googleapis.com/tf-datasets/titanic/train.csv") +pr = df.profile_report() + +st_profile_report(pr) +``` + +
+ + + +screenshot + +

Streamlit Ace

+ +Ace editor component for Streamlit. Created by [@okld](https://github.com/okld). + +```python +from streamlit_ace import st_ace + +content = st_ace() +content +``` + +
+ + + +screenshot + +

Streamlit Analytics

+ +Track & visualize user interactions with your streamlit app. Created by [@jrieke](https://github.com/jrieke). + +```python +import streamlit_analytics + +with streamlit_analytics.track(): + st.text_input("Write something") +``` + +
+ +
diff --git a/data/develop/api-reference/caching-and-state/_index.md b/data/develop/api-reference/caching-and-state/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..99ea9ecbe33a6ff48b42d7f7fe3ca535fd51b399 --- /dev/null +++ b/data/develop/api-reference/caching-and-state/_index.md @@ -0,0 +1,161 @@ +--- +title: Caching and state +slug: /develop/api-reference/caching-and-state +--- + +# Caching and state + +Optimize performance and add statefulness to your app! + +## Caching + +Streamlit provides powerful [cache primitives](/develop/concepts/architecture/caching) for data and global resources. They allow your app to stay performant even when loading data from the web, manipulating large datasets, or performing expensive computations. + + + + + +

Cache data

+ +Function decorator to cache functions that return data (e.g. dataframe transforms, database queries, ML inference). + +```python +@st.cache_data +def long_function(param1, param2): + # Perform expensive computation here or + # fetch data from the web here + return data +``` + +
+ + + +

Cache resource

+ +Function decorator to cache functions that return global resources (e.g. database connections, ML models). + +```python +@st.cache_resource +def init_model(): + # Return a global resource here + return pipeline( + "sentiment-analysis", + model="distilbert-base-uncased-finetuned-sst-2-english" + ) +``` + +
+ +
+ +## Manage state + +Streamlit re-executes your script with each user interaction. Widgets have built-in statefulness between reruns, but Session State lets you do more! + + + + +

Session State

+ +Save data between reruns and across pages. + +```python +st.session_state["foo"] = "bar" +``` + +
+ + +

Query parameters

+ +Get, set, or clear the query parameters that are shown in the browser's URL bar. + +```python +st.query_params[key] = value +st.query_params.clear() +``` + +
+ +
+ +## Deprecated commands + + + + + +> This command was deprecated in version 1.18.0. Use `st.cache_data` or `st.cache_resource` instead. + +

Caching

+ +Function decorator to memoize function executions. + +```python +@st.cache(ttl=3600) +def run_long_computation(arg1, arg2): + # Do stuff here + return computation_output +``` + +
+ + + +> This command was deprecated in version 1.18.0. Use `st.cache_data` instead. + +

Memo

+ +Experimental function decorator to memoize function executions. + +```python +@st.experimental_memo +def fetch_and_clean_data(url): + # Fetch data from URL here, and then clean it up. + return data +``` + +
+ + + +> This command was deprecated in version 1.18.0. Use `st.cache_resource` instead. + +

Singleton

+ +Experimental function decorator to store singleton objects. + +```python +@st.experimental_singleton +def get_database_session(url): + # Create a database session object that points to the URL. + return session +``` + +
+ + +

Get query parameters

+ +Get query parameters that are shown in the browser's URL bar. + +```python +param_dict = st.experimental_get_query_params() +``` + +
+ + +

Set query parameters

+ +Set query parameters that are shown in the browser's URL bar. + +```python +st.experimental_set_query_params( + {"show_all"=True, "selected"=["asia", "america"]} +) +``` + +
+
diff --git a/data/develop/api-reference/caching-and-state/cache-data.md b/data/develop/api-reference/caching-and-state/cache-data.md new file mode 100644 index 0000000000000000000000000000000000000000..f266865dbcae9316a7a1e94b2bd64f0f7d6d0a11 --- /dev/null +++ b/data/develop/api-reference/caching-and-state/cache-data.md @@ -0,0 +1,100 @@ +--- +title: st.cache_data +slug: /develop/api-reference/caching-and-state/st.cache_data +description: st.cache_data is used to cache functions that return data (e.g. dataframe transforms, database queries, ML inference). +--- + + + +This page only contains information on the `st.cache_data` API. For a deeper dive into caching and how to use it, check out [Caching](/develop/concepts/architecture/caching). + + + + + + + +`st.cache_data` implicitly uses the `pickle` module, which is known to be insecure. Anything your cached function returns is pickled and stored, then unpickled on retrieval. Ensure your cached functions return trusted values because it is possible to construct malicious pickle data that will execute arbitrary code during unpickling. Never load data that could have come from an untrusted source in an unsafe mode or that could have been tampered with. **Only load data you trust**. + + + + + +#### Example + +In the example below, pressing the "Clear All" button will clear memoized values from all functions decorated with `@st.cache_data`. + +```python +import streamlit as st + +@st.cache_data +def square(x): + return x**2 + +@st.cache_data +def cube(x): + return x**3 + +if st.button("Clear All"): + # Clear values from *all* all in-memory and on-disk data caches: + # i.e. clear values from both square and cube + st.cache_data.clear() +``` + + + +## Using Streamlit commands in cached functions + +### Static elements + +Since version 1.16.0, cached functions can contain Streamlit commands! For example, you can do this: + +```python +@st.cache_data +def get_api_data(): + data = api.get(...) + st.success("Fetched data from API!") # 👈 Show a success message + return data +``` + +As we know, Streamlit only runs this function if it hasn’t been cached before. On this first run, the `st.success` message will appear in the app. But what happens on subsequent runs? It still shows up! Streamlit realizes that there is an `st.` command inside the cached function, saves it during the first run, and replays it on subsequent runs. Replaying static elements works for both caching decorators. + +You can also use this functionality to cache entire parts of your UI: + +```python +@st.cache_data +def show_data(): + st.header("Data analysis") + data = api.get(...) + st.success("Fetched data from API!") + st.write("Here is a plot of the data:") + st.line_chart(data) + st.write("And here is the raw data:") + st.dataframe(data) +``` + +### Input widgets + +You can also use [interactive input widgets](/develop/api-reference/widgets) like `st.slider` or `st.text_input` in cached functions. Widget replay is an experimental feature at the moment. To enable it, you need to set the `experimental_allow_widgets` parameter: + +```python +@st.cache_data(experimental_allow_widgets=True) # 👈 Set the parameter +def get_data(): + num_rows = st.slider("Number of rows to get") # 👈 Add a slider + data = api.get(..., num_rows) + return data +``` + +Streamlit treats the slider like an additional input parameter to the cached function. If you change the slider position, Streamlit will see if it has already cached the function for this slider value. If yes, it will return the cached value. If not, it will rerun the function using the new slider value. + +Using widgets in cached functions is extremely powerful because it lets you cache entire parts of your app. But it can be dangerous! Since Streamlit treats the widget value as an additional input parameter, it can easily lead to excessive memory usage. Imagine your cached function has five sliders and returns a 100 MB DataFrame. Then we’ll add 100 MB to the cache for _every permutation_ of these five slider values – even if the sliders do not influence the returned data! These additions can make your cache explode very quickly. Please be aware of this limitation if you use widgets in cached functions. We recommend using this feature only for isolated parts of your UI where the widgets directly influence the cached return value. + + + +Support for widgets in cached functions is currently experimental. We may change or remove it anytime without warning. Please use it with care! + + + + +Two widgets are currently not supported in cached functions: `st.file_uploader` and `st.camera_input`. We may support them in the future. Feel free to [open a GitHub issue](https://github.com/streamlit/streamlit/issues) if you need them! + diff --git a/data/develop/api-reference/caching-and-state/cache-resource.md b/data/develop/api-reference/caching-and-state/cache-resource.md new file mode 100644 index 0000000000000000000000000000000000000000..2b3fbd433fed2d31bce0b5ee74a77406c316ed7d --- /dev/null +++ b/data/develop/api-reference/caching-and-state/cache-resource.md @@ -0,0 +1,98 @@ +--- +title: st.cache_resource +slug: /develop/api-reference/caching-and-state/st.cache_resource +description: st.cache_resource is used to cache functions that return shared global resources (e.g. database connections, ML models). +--- + + + +This page only contains information on the `st.cache_resource` API. For a deeper dive into caching and how to use it, check out [Caching](/develop/concepts/architecture/caching). + + + + + + + +#### Example + +In the example below, pressing the "Clear All" button will clear _all_ cache_resource caches. i.e. Clears cached global resources from all functions decorated with `@st.cache_resource`. + +```python +import streamlit as st +from transformers import BertModel + +@st.cache_resource + def get_database_session(url): + # Create a database session object that points to the URL. + return session + +@st.cache_resource +def get_model(model_type): + # Create a model of the specified type. + return BertModel.from_pretrained(model_type) + +if st.button("Clear All"): + # Clears all st.cache_resource caches: + st.cache_resource.clear() +``` + + + +## Using Streamlit commands in cached functions + +### Static elements + +Since version 1.16.0, cached functions can contain Streamlit commands! For example, you can do this: + +```python +from transformers import pipeline + +@st.cache_resource +def load_model(): + model = pipeline("sentiment-analysis") + st.success("Loaded NLP model from Hugging Face!") # 👈 Show a success message + return model +``` + +As we know, Streamlit only runs this function if it hasn’t been cached before. On this first run, the `st.success` message will appear in the app. But what happens on subsequent runs? It still shows up! Streamlit realizes that there is an `st.` command inside the cached function, saves it during the first run, and replays it on subsequent runs. Replaying static elements works for both caching decorators. + +You can also use this functionality to cache entire parts of your UI: + +```python +@st.cache_resource +def load_model(): + st.header("Data analysis") + model = torchvision.models.resnet50(weights=ResNet50_Weights.DEFAULT) + st.success("Loaded model!") + st.write("Turning on evaluation mode...") + model.eval() + st.write("Here's the model:") + return model +``` + +### Input widgets + +You can also use [interactive input widgets](/develop/api-reference/widgets) like `st.slider` or `st.text_input` in cached functions. Widget replay is an experimental feature at the moment. To enable it, you need to set the `experimental_allow_widgets` parameter: + +```python +@st.cache_resource(experimental_allow_widgets=True) # 👈 Set the parameter +def load_model(): + pretrained = st.checkbox("Use pre-trained model:") # 👈 Add a checkbox + model = torchvision.models.resnet50(weights=ResNet50_Weights.DEFAULT, pretrained=pretrained) + return model +``` + +Streamlit treats the checkbox like an additional input parameter to the cached function. If you uncheck it, Streamlit will see if it has already cached the function for this checkbox state. If yes, it will return the cached value. If not, it will rerun the function using the new slider value. + +Using widgets in cached functions is extremely powerful because it lets you cache entire parts of your app. But it can be dangerous! Since Streamlit treats the widget value as an additional input parameter, it can easily lead to excessive memory usage. Imagine your cached function has five sliders and returns a 100 MB DataFrame. Then we’ll add 100 MB to the cache for _every permutation_ of these five slider values – even if the sliders do not influence the returned data! These additions can make your cache explode very quickly. Please be aware of this limitation if you use widgets in cached functions. We recommend using this feature only for isolated parts of your UI where the widgets directly influence the cached return value. + + + +Support for widgets in cached functions is currently experimental. We may change or remove it anytime without warning. Please use it with care! + + + + +Two widgets are currently not supported in cached functions: `st.file_uploader` and `st.camera_input`. We may support them in the future. Feel free to [open a GitHub issue](https://github.com/streamlit/streamlit/issues) if you need them! + diff --git a/data/develop/api-reference/caching-and-state/query_params.md b/data/develop/api-reference/caching-and-state/query_params.md new file mode 100644 index 0000000000000000000000000000000000000000..c47662f3c12ce7d3fdfe443fcd656b64b39be6aa --- /dev/null +++ b/data/develop/api-reference/caching-and-state/query_params.md @@ -0,0 +1,58 @@ +--- +title: st.query_params +slug: /develop/api-reference/caching-and-state/st.query_params +description: st.query_params reads and manipulates query parameters in the browser's URL bar. +--- + +## st.query_params + +`st.query_params` provides a dictionary-like interface to access query parameters in your app's URL and is available as of Streamlit 1.30.0. It behaves similarly to `st.session_state` with the notable exception that keys may be repeated in an app's URL. Handling of repeated keys requires special consideration as explained below. + +`st.query_params` can be used with both key and attribute notation. For example, `st.query_params.my_key` and `st.query_params["my_key"]`. All keys and values will be set and returned as strings. When you write to `st.query_params`, key-value pair prefixed with `?` is added to the end of your app's URL. Each additional pair is prefixed with `&` instead of `?`. Query parameters are cleared when navigating between pages in a multipage app. + +For example, consider the following URL: + +```javascript +https://your_app.streamlit.app/?first_key=1&second_key=two&third_key=true +``` + +The parameters in the URL above will be accessible in `st.query_params` as: + +```python +{ + "first_key" : "1", + "second_key" : "two", + "third_key" : "true" +} +``` + +This means you can use those parameters in your app like this: + +```python +# You can read query params using key notation +if st.query_params["first_key"] == "1": + do_something() + +# ...or using attribute notation +if st.query_params.second_key == "two": + do_something_else() + +# And you can change a param by just writing to it +st.query_params.first_key = 2 # This gets converted to str automatically +``` + +### Repeated keys + +When a key is repeated in your app's URL (`?a=1&a=2&a=3`), dict-like methods will return only the last value. In this example, `st.query_params["a"]` returns `"3"`. To get all keys as a list, use the [`.get_all()`](/develop/api-reference/caching-and-state/st.query_params#stquery_paramsget_all) method shown below. To set the value of a repeated key, assign the values as a list. For example, `st.query_params.a = ["1", "2", "3"]` produces the repeated key given at the beginning of this paragraph. + +### Limitation + +`st.query_params` can't get or set embedding settings as described in [Embed your app](/deploy/streamlit-community-cloud/share-your-app/embed-your-app#embed-options). `st.query_params.embed` and `st.query_params.embed_options` will raise an `AttributeError` or `StreamlitAPIException` when trying to get or set their values, respectively. + + + + + + + + diff --git a/data/develop/api-reference/caching-and-state/session_state.md b/data/develop/api-reference/caching-and-state/session_state.md new file mode 100644 index 0000000000000000000000000000000000000000..17480f7cef1425ab8bb94ed88dacc2bd73940c19 --- /dev/null +++ b/data/develop/api-reference/caching-and-state/session_state.md @@ -0,0 +1,224 @@ +--- +title: Session State +slug: /develop/api-reference/caching-and-state/st.session_state +description: st.session_state is a way to share variables between reruns, for each user session. +--- + +# Session State + +Session State is a way to share variables between reruns, for each user session. In addition to the ability to store and persist state, Streamlit also exposes the ability to manipulate state using Callbacks. Session state also persists across apps inside a [multipage app](/develop/concepts/multipage-apps). + +Check out this Session State basics tutorial video by Streamlit Developer Advocate Dr. Marisa Smith to get started: + + + +### Initialize values in Session State + +The Session State API follows a field-based API, which is very similar to Python dictionaries: + +```python +# Initialization +if 'key' not in st.session_state: + st.session_state['key'] = 'value' + +# Session State also supports attribute based syntax +if 'key' not in st.session_state: + st.session_state.key = 'value' +``` + +### Reads and updates + +Read the value of an item in Session State and display it by passing to `st.write` : + +```python +# Read +st.write(st.session_state.key) + +# Outputs: value +``` + +Update an item in Session State by assigning it a value: + +```python +st.session_state.key = 'value2' # Attribute API +st.session_state['key'] = 'value2' # Dictionary like API +``` + +Curious about what is in Session State? Use `st.write` or magic: + +```python +st.write(st.session_state) + +# With magic: +st.session_state +``` + +Streamlit throws a handy exception if an uninitialized variable is accessed: + +```python +st.write(st.session_state['value']) + +# Throws an exception! +``` + +![state-uninitialized-exception](/images/state_uninitialized_exception.png) + +### Delete items + +Delete items in Session State using the syntax to delete items in any Python dictionary: + +```python +# Delete a single key-value pair +del st.session_state[key] + +# Delete all the items in Session state +for key in st.session_state.keys(): + del st.session_state[key] +``` + +Session State can also be cleared by going to Settings → Clear Cache, followed by Rerunning the app. + +![state-clear-cache](/images/clear_cache.png) + +### Session State and Widget State association + +Every widget with a key is automatically added to Session State: + +```python +st.text_input("Your name", key="name") + +# This exists now: +st.session_state.name +``` + +### Use Callbacks to update Session State + +A callback is a python function which gets called when an input widget changes. + +**Order of execution**: When updating Session state in response to **events**, a callback function gets executed first, and then the app is executed from top to bottom. + +Callbacks can be used with widgets using the parameters `on_change` (or `on_click`), `args`, and `kwargs`: + +**Parameters** + +- **on_change** or **on_click** - The function name to be used as a callback +- **args** (_tuple_) - List of arguments to be passed to the callback function +- **kwargs** (_dict_) - Named arguments to be passed to the callback function + +Widgets which support the `on_change` event: + +- `st.checkbox` +- `st.color_picker` +- `st.date_input` +- `st.data_editor` +- `st.file_uploader` +- `st.multiselect` +- `st.number_input` +- `st.radio` +- `st.select_slider` +- `st.selectbox` +- `st.slider` +- `st.text_area` +- `st.text_input` +- `st.time_input` +- `st.toggle` + +Widgets which support the `on_click` event: + +- `st.button` +- `st.download_button` +- `st.form_submit_button` + +To add a callback, define a callback function **above** the widget declaration and pass it to the widget via the `on_change` (or `on_click` ) parameter. + +### Forms and Callbacks + +Widgets inside a form can have their values be accessed and set via the Session State API. `st.form_submit_button` can have a callback associated with it. The callback gets executed upon clicking on the submit button. For example: + +```python +def form_callback(): + st.write(st.session_state.my_slider) + st.write(st.session_state.my_checkbox) + +with st.form(key='my_form'): + slider_input = st.slider('My slider', 0, 10, 5, key='my_slider') + checkbox_input = st.checkbox('Yes or No', key='my_checkbox') + submit_button = st.form_submit_button(label='Submit', on_click=form_callback) +``` + +### Serializable Session State + +Serialization refers to the process of converting an object or data structure into a format that can be persisted and shared, and allowing you to recover the data’s original structure. Python’s built-in [pickle](https://docs.python.org/3/develop/pickle.html) module serializes Python objects to a byte stream ("pickling") and deserializes the stream into an object ("unpickling"). + +By default, Streamlit’s [Session State](/develop/concepts/architecture/session-state) allows you to persist any Python object for the duration of the session, irrespective of the object’s pickle-serializability. This property lets you store Python primitives such as integers, floating-point numbers, complex numbers and booleans, dataframes, and even [lambdas](https://docs.python.org/3/reference/expressions.html#lambda) returned by functions. However, some execution environments may require serializing all data in Session State, so it may be useful to detect incompatibility during development, or when the execution environment will stop supporting it in the future. + +To that end, Streamlit provides a `runner.enforceSerializableSessionState` [configuration option](/develop/concepts/configuration) that, when set to `true`, only allows pickle-serializable objects in Session State. To enable the option, either create a global or project config file with the following or use it as a command-line flag: + +```toml +# .streamlit/config.toml +[runner] +enforceSerializableSessionState = true +``` + +By "_pickle-serializable_", we mean calling `pickle.dumps(obj)` should not raise a [`PicklingError`](https://docs.python.org/3/develop/pickle.html#pickle.PicklingError) exception. When the config option is enabled, adding unserializable data to session state should result in an exception. E.g., + +```python +import streamlit as st + +def unserializable_data(): + return lambda x: x + +#👇 results in an exception when enforceSerializableSessionState is on +st.session_state.unserializable = unserializable_data() +``` + +UnserializableSessionStateError + + + +When `runner.enforceSerializableSessionState` is set to `true`, Session State implicitly uses the `pickle` module, which is known to be insecure. Ensure all data saved and retrieved from Session State is trusted because it is possible to construct malicious pickle data that will execute arbitrary code during unpickling. Never load data that could have come from an untrusted source in an unsafe mode or that could have been tampered with. **Only load data you trust**. + + + +### Caveats and limitations + +- Only the `st.form_submit_button` has a callback in forms. Other widgets inside a form are not allowed to have callbacks. +- `on_change` and `on_click` events are only supported on input type widgets. +- Modifying the value of a widget via the Session state API, after instantiating it, is not allowed and will raise a `StreamlitAPIException`. For example: + + ```python + slider = st.slider( + label='My Slider', min_value=1, + max_value=10, value=5, key='my_slider') + + st.session_state.my_slider = 7 + + # Throws an exception! + ``` + + ![state-modified-instantiated-exception](/images/state_modified_instantiated_exception.png) + +- Setting the widget state via the Session State API and using the `value` parameter in the widget declaration is not recommended, and will throw a warning on the first run. For example: + + ```python + st.session_state.my_slider = 7 + + slider = st.slider( + label='Choose a Value', min_value=1, + max_value=10, value=5, key='my_slider') + ``` + + ![state-value-api-exception](/images/state_value_api_exception.png) + +- Setting the state of button-like widgets: `st.button`, `st.download_button`, and `st.file_uploader` via the Session State API is not allowed. Such type of widgets are by default _False_ and have ephemeral _True_ states which are only valid for a single run. For example: + + ```python + if 'my_button' not in st.session_state: + st.session_state.my_button = True + + st.button('My button', key='my_button') + + # Throws an exception! + ``` + + ![state-button-exception](/images/state_button_exception.png) diff --git a/data/develop/api-reference/charts/_index.md b/data/develop/api-reference/charts/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..a37d23f54207150c3e1963dee289799d76438fb1 --- /dev/null +++ b/data/develop/api-reference/charts/_index.md @@ -0,0 +1,308 @@ +--- +title: Chart elements +slug: /develop/api-reference/charts +--- + +# Chart elements + +Streamlit supports several different charting libraries, and our goal is to +continually add support for more. Right now, the most basic library in our +arsenal is [Matplotlib](https://matplotlib.org/). Then there are also +interactive charting libraries like [Vega +Lite](https://vega.github.io/vega-lite/) (2D charts) and +[deck.gl](https://github.com/uber/deck.gl) (maps and 3D charts). And +finally we also provide a few chart types that are "native" to Streamlit, +like `st.line_chart` and `st.area_chart`. + +## Simple chart elements + + + +screenshot + +

Simple area charts

+ +Display an area chart. + +```python +st.area_chart(my_data_frame) +``` + +
+ +screenshot + +

Simple bar charts

+ +Display a bar chart. + +```python +st.bar_chart(my_data_frame) +``` + +
+ +screenshot + +

Simple line charts

+ +Display a line chart. + +```python +st.line_chart(my_data_frame) +``` + +
+ +screenshot + +

Simple scatter charts

+ +Display a line chart. + +```python +st.scatter_chart(my_data_frame) +``` + +
+ +screenshot + +

Scatterplots on maps

+ +Display a map with points on it. + +```python +st.map(my_data_frame) +``` + +
+
+ +## Advanced chart elements + + + +screenshot + +

Matplotlib

+ +Display a matplotlib.pyplot figure. + +```python +st.pyplot(my_mpl_figure) +``` + +
+ +screenshot + +

Altair

+ +Display a chart using the Altair library. + +```python +st.altair_chart(my_altair_chart) +``` + +
+ +screenshot + +

Vega-Lite

+ +Display a chart using the Vega-Lite library. + +```python +st.vega_lite_chart(my_vega_lite_chart) +``` + +
+ +screenshot + +

Plotly

+ +Display an interactive Plotly chart. + +```python +st.plotly_chart(my_plotly_chart) +``` + +
+ +screenshot + +

Bokeh

+ +Display an interactive Bokeh chart. + +```python +st.bokeh_chart(my_bokeh_chart) +``` + +
+ +screenshot + +

PyDeck

+ +Display a chart using the PyDeck library. + +```python +st.pydeck_chart(my_pydeck_chart) +``` + +
+ +screenshot + +

GraphViz

+ +Display a graph using the dagre-d3 library. + +```python +st.graphviz_chart(my_graphviz_spec) +``` + +
+
+ + + + + +screenshot + +

Plost

+ +A deceptively simple plotting library for Streamlit. Created by [@tvst](https://github.com/tvst). + +```python +import plost +plost.line_chart(my_dataframe, x='time', y='stock_value', color='stock_name',) +``` + +
+ + + +screenshot + +

HiPlot

+ +High dimensional Interactive Plotting. Created by [@facebookresearch](https://github.com/facebookresearch). + +```python +data = [{'dropout':0.1, 'lr': 0.001, 'loss': 10.0, 'optimizer': 'SGD'}, {'dropout':0.15, 'lr': 0.01, 'loss': 3.5, 'optimizer': 'Adam'}, {'dropout':0.3, 'lr': 0.1, 'loss': 4.5, 'optimizer': 'Adam'}] +hip.Experiment.from_iterable(data).display() +``` + +
+ + + +screenshot + +

ECharts

+ +High dimensional Interactive Plotting. Created by [@andfanilo](https://github.com/andfanilo). + +```python +from streamlit_echarts import st_echarts +st_echarts(options=options) +``` + +
+ + + +screenshot + +

Streamlit Folium

+ +Streamlit Component for rendering Folium maps. Created by [@randyzwitch](https://github.com/randyzwitch). + +```python +m = folium.Map(location=[39.949610, -75.150282], zoom_start=16) +st_data = st_folium(m, width=725) +``` + +
+ + + +screenshot + +

Spacy-Streamlit

+ +spaCy building blocks and visualizers for Streamlit apps. Created by [@explosion](https://github.com/explosion). + +```python +models = ["en_core_web_sm", "en_core_web_md"] +spacy_streamlit.visualize(models, "Sundar Pichai is the CEO of Google.") +``` + +
+ + + +screenshot + +

Streamlit Agraph

+ +A Streamlit Graph Vis, based on [react-grah-vis](https://github.com/crubier/react-graph-vis). Created by [@ChrisDelClea](https://github.com/ChrisDelClea). + +```python +from streamlit_agraph import agraph, Node, Edge, Config +agraph(nodes=nodes, edges=edges, config=config) +``` + +
+ + + +screenshot + +

Streamlit Lottie

+ +Integrate [Lottie](https://lottiefiles.com/) animations inside your Streamlit app. Created by [@andfanilo](https://github.com/andfanilo). + +```python +lottie_hello = load_lottieurl("https://assets5.lottiefiles.com/packages/lf20_V9t630.json") +st_lottie(lottie_hello, key="hello") +``` + +
+ + + +screenshot + +

Plotly Events

+ +Make Plotly charts interactive!. Created by [@null-jones](https://github.com/null-jones/). + +```python +fig = px.line(x=[1], y=[1]) +selected_points = plotly_events(fig) +``` + +
+ + + +screenshot + +

Streamlit Extras

+ +A library with useful Streamlit extras. Created by [@arnaudmiribel](https://github.com/arnaudmiribel/). + +```python +chart += get_annotations_chart(annotations=[("Mar 01, 2008", "Pretty good day for GOOG"), ("Dec 01, 2007", "Something's going wrong for GOOG & AAPL"), ("Nov 01, 2008", "Market starts again thanks to..."), ("Dec 01, 2009", "Small crash for GOOG after..."),],) +st.altair_chart(chart, use_container_width=True) +``` + +
+ +
diff --git a/data/develop/api-reference/charts/altair_chart.md b/data/develop/api-reference/charts/altair_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..460b9bd9a8a076be5559f3896a4f337ca3e99256 --- /dev/null +++ b/data/develop/api-reference/charts/altair_chart.md @@ -0,0 +1,266 @@ +--- +title: st.altair_chart +slug: /develop/api-reference/charts/st.altair_chart +description: st.altair_chart displays a chart using the Altair library. +--- + + + +### Theming + +Altair charts are displayed using the Streamlit theme by default. This theme is sleek, user-friendly, and incorporates Streamlit's color palette. The added benefit is that your charts better integrate with the rest of your app's design. + +The Streamlit theme is available from Streamlit 1.16.0 through the `theme="streamlit"` keyword argument. To disable it, and use Altair's native theme, use `theme=None` instead. + +Let's look at an example of charts with the Streamlit theme and the native Altair theme: + +```python +import altair as alt +from vega_datasets import data + +source = data.cars() + +chart = alt.Chart(source).mark_circle().encode( + x='Horsepower', + y='Miles_per_Gallon', + color='Origin', +).interactive() + +tab1, tab2 = st.tabs(["Streamlit theme (default)", "Altair native theme"]) + +with tab1: + # Use the Streamlit theme. + # This is the default. So you can also omit the theme argument. + st.altair_chart(chart, theme="streamlit", use_container_width=True) +with tab2: + # Use the native Altair theme. + st.altair_chart(chart, theme=None, use_container_width=True) +``` + +Click the tabs in the interactive app below to see the charts with the Streamlit theme enabled and disabled. + + + +If you're wondering if your own customizations will still be taken into account, don't worry! You can still make changes to your chart configurations. In other words, although we now enable the Streamlit theme by default, you can overwrite it with custom colors or fonts. For example, if you want a chart line to be green instead of the default red, you can do it! + +Here's an example of an Altair chart where manual color passing is done and reflected: + + + +```python +import altair as alt +import streamlit as st +from vega_datasets import data + +source = data.seattle_weather() + +scale = alt.Scale( + domain=["sun", "fog", "drizzle", "rain", "snow"], + range=["#e7ba52", "#a7a7a7", "#aec7e8", "#1f77b4", "#9467bd"], +) +color = alt.Color("weather:N", scale=scale) + +# We create two selections: +# - a brush that is active on the top panel +# - a multi-click that is active on the bottom panel +brush = alt.selection_interval(encodings=["x"]) +click = alt.selection_multi(encodings=["color"]) + +# Top panel is scatter plot of temperature vs time +points = ( + alt.Chart() + .mark_point() + .encode( + alt.X("monthdate(date):T", title="Date"), + alt.Y( + "temp_max:Q", + title="Maximum Daily Temperature (C)", + scale=alt.Scale(domain=[-5, 40]), + ), + color=alt.condition(brush, color, alt.value("lightgray")), + size=alt.Size("precipitation:Q", scale=alt.Scale(range=[5, 200])), + ) + .properties(width=550, height=300) + .add_selection(brush) + .transform_filter(click) +) + +# Bottom panel is a bar chart of weather type +bars = ( + alt.Chart() + .mark_bar() + .encode( + x="count()", + y="weather:N", + color=alt.condition(click, color, alt.value("lightgray")), + ) + .transform_filter(brush) + .properties( + width=550, + ) + .add_selection(click) +) + +chart = alt.vconcat(points, bars, data=source, title="Seattle Weather: 2012-2015") + +tab1, tab2 = st.tabs(["Streamlit theme (default)", "Altair native theme"]) + +with tab1: + st.altair_chart(chart, theme="streamlit", use_container_width=True) +with tab2: + st.altair_chart(chart, theme=None, use_container_width=True) +``` + + + +Notice how the custom colors are still reflected in the chart, even when the Streamlit theme is enabled 👇 + + + +For many more examples of Altair charts with and without the Streamlit theme, check out the [altair.streamlit.app](https://altair.streamlit.app). + +### Annotating charts + +Altair also allows you to annotate your charts with text, images, and emojis. You can do this by creating [layered charts](https://altair-viz.github.io/user_guide/compound_charts.html#layered-charts), which let you overlay two different charts on top of each other. The idea is to use the first chart to show the data, and the second chart to show the annotations. The second chart can then be overlaid on top of the first chart using the `+` operator to create a layered chart. + +Let's walk through an example of annotating a time-series chart with text and an emoji. + +#### Step 1: Create the base chart + +In this example, we create a time-series chart to track the evolution of stock prices. The chart is interactive and contains a multi-line tooltip. Click [here](https://altair-viz.github.io/gallery/multiline_tooltip.html) to learn more about multi-line tooltips in Altair. + +First, we import the required libraries and load the example stocks dataset using the [`vega_datasets`](https://pypi.org/project/vega-datasets/) package: + +```python +import altair as alt +import pandas as pd +import streamlit as st +from vega_datasets import data + +# We use @st.cache_data to keep the dataset in cache +@st.cache_data +def get_data(): + source = data.stocks() + source = source[source.date.gt("2004-01-01")] + return source + +source = get_data() +``` + +Next, we define a function `get_chart()` to create the interactive time-series chart of the stock prices with a multi-line tooltip. The x-axis represents the date, and the y-axis represents the stock price. + +We then invoke `get_chart()` that takes the stock prices dataframe as an input and returns a chart object. This is going to be our base chart on which we will overlay the annotations in [Step 2](/develop/api-reference/charts/st.altair_chart#step-2-annotate-the-chart). + +```python +# Define the base time-series chart. +def get_chart(data): + hover = alt.selection_single( + fields=["date"], + nearest=True, + on="mouseover", + empty="none", + ) + + lines = ( + alt.Chart(data, title="Evolution of stock prices") + .mark_line() + .encode( + x="date", + y="price", + color="symbol", + ) + ) + + # Draw points on the line, and highlight based on selection + points = lines.transform_filter(hover).mark_circle(size=65) + + # Draw a rule at the location of the selection + tooltips = ( + alt.Chart(data) + .mark_rule() + .encode( + x="yearmonthdate(date)", + y="price", + opacity=alt.condition(hover, alt.value(0.3), alt.value(0)), + tooltip=[ + alt.Tooltip("date", title="Date"), + alt.Tooltip("price", title="Price (USD)"), + ], + ) + .add_selection(hover) + ) + return (lines + points + tooltips).interactive() + +chart = get_chart(source) +``` + +#### Step 2: Annotate the chart + +Now that we have our first chart that shows the data, we can annotate it with text and an emoji. Let's overlay the ⬇ emoji on top of the time-series chart at specifc points of interest. We want users to hover over the ⬇ emoji to see the associated annotation text. + +For simplicity, let's annotate four specific dates and set the height of the annotations at constant value of `10`. + + + +You can vary the horizontal and vertical postions of the annotations by replacing the hard-coded values with the output of Streamlit widgets! Click [here](/develop/api-reference/charts/st.altair_chart#interactive-example) to jump to a live example below, and develop an intuition for the ideal horizontal and vertical positions of the annotations by playing with Streamlit widgets. + + + +To do so, we create a dataframe `annotations_df` containing the dates, annotation text, and the height of the annotations: + +```python +# Add annotations +ANNOTATIONS = [ + ("Mar 01, 2008", "Pretty good day for GOOG"), + ("Dec 01, 2007", "Something's going wrong for GOOG & AAPL"), + ("Nov 01, 2008", "Market starts again thanks to..."), + ("Dec 01, 2009", "Small crash for GOOG after..."), +] +annotations_df = pd.DataFrame(ANNOTATIONS, columns=["date", "event"]) +annotations_df.date = pd.to_datetime(annotations_df.date) +annotations_df["y"] = 10 +``` + +Using this dataframe, we create a scatter plot with the x-axis representing the date, and the y-axis representing the height of the annotation. The data point at the specific date and height is represented by the ⬇ emoji, using Altair's `mark_text()` [mark](https://altair-viz.github.io/user_guide/marks.html). + +The annotation text is displayed as a tooltip when users hover over the ⬇ emoji. This is achieved using Altair's `encode()` method to map the `event` column containing the annotation text to the visual attribute ⬇ of the plot. + +```python +annotation_layer = ( + alt.Chart(annotations_df) + .mark_text(size=20, text="⬇", dx=-8, dy=-10, align="left") + .encode( + x="date:T", + y=alt.Y("y:Q"), + tooltip=["event"], + ) + .interactive() +) +``` + +Finally, we overlay the annotations on top of the base chart using the `+` operator to create the final layered chart! 🎈 + +```python +st.altair_chart( + (chart + annotation_layer).interactive(), + use_container_width=True +) +``` + + + +To use images instead of emojis, replace the line containing `.mark_text()` with `.mark_image()`, and replace `image_url` below with the URL of the image: + +```python +.mark_image( + width=12, + height=12, + url="image_url", +) +``` + +#### Interactive example + +Now that you've learned how to annotate charts, the sky's the limit! We've extended the above example to let you interactively paste your favorite emoji and set its position on the chart with Streamlit widgets. 👇 + + diff --git a/data/develop/api-reference/charts/area_chart.md b/data/develop/api-reference/charts/area_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..50bbbf71cf47af9719aee431ebbd3d07dbac0364 --- /dev/null +++ b/data/develop/api-reference/charts/area_chart.md @@ -0,0 +1,9 @@ +--- +title: st.area_chart +slug: /develop/api-reference/charts/st.area_chart +description: st.area_chart displays an area chart. +--- + + + + diff --git a/data/develop/api-reference/charts/bar_chart.md b/data/develop/api-reference/charts/bar_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..7500ecc2673c65ef91df83bec81711d8159e5f99 --- /dev/null +++ b/data/develop/api-reference/charts/bar_chart.md @@ -0,0 +1,9 @@ +--- +title: st.bar_chart +slug: /develop/api-reference/charts/st.bar_chart +description: st.bar_chart displays a bar chart. +--- + + + + diff --git a/data/develop/api-reference/charts/bokeh_chart.md b/data/develop/api-reference/charts/bokeh_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..1195e4deaa1b0126584f612c5967093918a5b9c6 --- /dev/null +++ b/data/develop/api-reference/charts/bokeh_chart.md @@ -0,0 +1,7 @@ +--- +title: st.bokeh_chart +slug: /develop/api-reference/charts/st.bokeh_chart +description: st.bokeh_chart displays an interactive Bokeh chart. +--- + + diff --git a/data/develop/api-reference/charts/graphviz_chart.md b/data/develop/api-reference/charts/graphviz_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..f0a7a643c2a1383399aa6610d23dd5d327635dbb --- /dev/null +++ b/data/develop/api-reference/charts/graphviz_chart.md @@ -0,0 +1,7 @@ +--- +title: st.graphviz_chart +slug: /develop/api-reference/charts/st.graphviz_chart +description: st.graphviz_chart displays a graph using the dagre-d3 library. +--- + + diff --git a/data/develop/api-reference/charts/line_chart.md b/data/develop/api-reference/charts/line_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..f0c8730b9b9c36d8b545b9d9f14f83b804c449c2 --- /dev/null +++ b/data/develop/api-reference/charts/line_chart.md @@ -0,0 +1,9 @@ +--- +title: st.line_chart +slug: /develop/api-reference/charts/st.line_chart +description: st.line_chart displays a line chart. +--- + + + + diff --git a/data/develop/api-reference/charts/map.md b/data/develop/api-reference/charts/map.md new file mode 100644 index 0000000000000000000000000000000000000000..bcfde0b52987c6e2006f2cf52fed31ff8c92048f --- /dev/null +++ b/data/develop/api-reference/charts/map.md @@ -0,0 +1,9 @@ +--- +title: st.map +slug: /develop/api-reference/charts/st.map +description: st.map displays a map with points on it. +--- + + + + diff --git a/data/develop/api-reference/charts/plotly_chart.md b/data/develop/api-reference/charts/plotly_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..c0d461f2b5cb6a8269ed3dbf721b1e9122787f5a --- /dev/null +++ b/data/develop/api-reference/charts/plotly_chart.md @@ -0,0 +1,77 @@ +--- +title: st.plotly_chart +slug: /develop/api-reference/charts/st.plotly_chart +description: st.plotly_chart displays an interactive Plotly chart. +--- + + + +### Theming + +Plotly charts are displayed using the Streamlit theme by default. This theme is sleek, user-friendly, and incorporates Streamlit's color palette. The added benefit is that your charts better integrate with the rest of your app's design. + +The Streamlit theme is available from Streamlit 1.16.0 through the `theme="streamlit"` keyword argument. To disable it, and use Plotly's native theme, use `theme=None` instead. + +Let's look at an example of charts with the Streamlit theme and the native Plotly theme: + +```python +import plotly.express as px +import streamlit as st + +df = px.data.gapminder() + +fig = px.scatter( + df.query("year==2007"), + x="gdpPercap", + y="lifeExp", + size="pop", + color="continent", + hover_name="country", + log_x=True, + size_max=60, +) + +tab1, tab2 = st.tabs(["Streamlit theme (default)", "Plotly native theme"]) +with tab1: + # Use the Streamlit theme. + # This is the default. So you can also omit the theme argument. + st.plotly_chart(fig, theme="streamlit", use_container_width=True) +with tab2: + # Use the native Plotly theme. + st.plotly_chart(fig, theme=None, use_container_width=True) +``` + +Click the tabs in the interactive app below to see the charts with the Streamlit theme enabled and disabled. + + + +If you're wondering if your own customizations will still be taken into account, don't worry! You can still make changes to your chart configurations. In other words, although we now enable the Streamlit theme by default, you can overwrite it with custom colors or fonts. For example, if you want a chart line to be green instead of the default red, you can do it! + +Here's an example of an Plotly chart where a custom color scale is defined and reflected: + +```python +import plotly.express as px +import streamlit as st + +st.subheader("Define a custom colorscale") +df = px.data.iris() +fig = px.scatter( + df, + x="sepal_width", + y="sepal_length", + color="sepal_length", + color_continuous_scale="reds", +) + +tab1, tab2 = st.tabs(["Streamlit theme (default)", "Plotly native theme"]) +with tab1: + st.plotly_chart(fig, theme="streamlit", use_container_width=True) +with tab2: + st.plotly_chart(fig, theme=None, use_container_width=True) +``` + +Notice how the custom color scale is still reflected in the chart, even when the Streamlit theme is enabled 👇 + + + +For many more examples of Plotly charts with and without the Streamlit theme, check out the [plotly.streamlit.app](https://plotly.streamlit.app). diff --git a/data/develop/api-reference/charts/pydeck_chart.md b/data/develop/api-reference/charts/pydeck_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..abf4c59ab17e8f7653911a0cb12cebdd2d2fb7b4 --- /dev/null +++ b/data/develop/api-reference/charts/pydeck_chart.md @@ -0,0 +1,7 @@ +--- +title: st.pydeck_chart +slug: /develop/api-reference/charts/st.pydeck_chart +description: st.pydeck_chart displays a chart using the PyDeck library. +--- + + diff --git a/data/develop/api-reference/charts/pyplot.md b/data/develop/api-reference/charts/pyplot.md new file mode 100644 index 0000000000000000000000000000000000000000..bfff466ecaf55079b745c2a28b1ffbd332fb3bc2 --- /dev/null +++ b/data/develop/api-reference/charts/pyplot.md @@ -0,0 +1,7 @@ +--- +title: st.pyplot +slug: /develop/api-reference/charts/st.pyplot +description: st.pyplot displays a matplotlib.pyplot figure. +--- + + diff --git a/data/develop/api-reference/charts/scatter_chart.md b/data/develop/api-reference/charts/scatter_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..237a1061fd60d17f4f9e4b52f92754628cb8fde2 --- /dev/null +++ b/data/develop/api-reference/charts/scatter_chart.md @@ -0,0 +1,9 @@ +--- +title: st.scatter_chart +slug: /develop/api-reference/charts/st.scatter_chart +description: st.scatter_chart displays an scatter chart. +--- + + + + diff --git a/data/develop/api-reference/charts/vega_lite_chart.md b/data/develop/api-reference/charts/vega_lite_chart.md new file mode 100644 index 0000000000000000000000000000000000000000..6a82c6e3db31a17ea611809e05f0947d4d85752d --- /dev/null +++ b/data/develop/api-reference/charts/vega_lite_chart.md @@ -0,0 +1,59 @@ +--- +title: st.vega_lite_chart +slug: /develop/api-reference/charts/st.vega_lite_chart +description: st.vega_lite_chart displays a chart using the Vega-Lite library. +--- + + + + + +### Theming + +Vega-Lite charts are displayed using the Streamlit theme by default. This theme is sleek, user-friendly, and incorporates Streamlit's color palette. The added benefit is that your charts better integrate with the rest of your app's design. + +The Streamlit theme is available from Streamlit 1.16.0 through the `theme="streamlit"` keyword argument. To disable it, and use Vega-Lite's native theme, use `theme=None` instead. + +Let's look at an example of charts with the Streamlit theme and the native Vega-Lite theme: + +```python +import streamlit as st +from vega_datasets import data + +source = data.cars() + +chart = { + "mark": "point", + "encoding": { + "x": { + "field": "Horsepower", + "type": "quantitative", + }, + "y": { + "field": "Miles_per_Gallon", + "type": "quantitative", + }, + "color": {"field": "Origin", "type": "nominal"}, + "shape": {"field": "Origin", "type": "nominal"}, + }, +} + +tab1, tab2 = st.tabs(["Streamlit theme (default)", "Vega-Lite native theme"]) + +with tab1: + # Use the Streamlit theme. + # This is the default. So you can also omit the theme argument. + st.vega_lite_chart( + source, chart, theme="streamlit", use_container_width=True + ) +with tab2: + st.vega_lite_chart( + source, chart, theme=None, use_container_width=True + ) +``` + +Click the tabs in the interactive app below to see the charts with the Streamlit theme enabled and disabled. + + + +If you're wondering if your own customizations will still be taken into account, don't worry! You can still make changes to your chart configurations. In other words, although we now enable the Streamlit theme by default, you can overwrite it with custom colors or fonts. For example, if you want a chart line to be green instead of the default red, you can do it! diff --git a/data/develop/api-reference/chat/_index.md b/data/develop/api-reference/chat/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..cc28fba5df33b850cb8b3af8badbd3c52de5ebd8 --- /dev/null +++ b/data/develop/api-reference/chat/_index.md @@ -0,0 +1,70 @@ +--- +title: Chat elements +slug: /develop/api-reference/chat +--- + +# Chat elements + +Streamlit provides a few commands to help you build conversational apps. These chat elements are designed to be used in conjunction with each other, but you can also use them separately. + +`st.chat_message` lets you insert a chat message container into the app so you can display messages from the user or the app. Chat containers can contain other Streamlit elements, including charts, tables, text, and more. `st.chat_input` lets you display a chat input widget so the user can type in a message. Remember to check out `st.status` to display output from long-running processes and external API calls. + + + + +screenshot + +

Chat input

+ +Display a chat input widget. + +```python +prompt = st.chat_input("Say something") +if prompt: + st.write(f"The user has sent: {prompt}") +``` + +
+ + +screenshot + +

Chat message

+ +Insert a chat message container. + +```python +import numpy as np +with st.chat_message("user"): + st.write("Hello 👋") + st.line_chart(np.random.randn(30, 3)) +``` + +
+ + +screenshot + +

Status container

+ +Display output of long-running tasks in a container. + +```python +with st.status('Running'): + do_something_slow() +``` + +
+ + +

st.write_stream

+ +Write generators or streams to the app with a typewriter effect. + +```python +st.write_stream(my_generator) +st.write_stream(my_llm_stream) +``` + +
+
diff --git a/data/develop/api-reference/chat/chat-input.md b/data/develop/api-reference/chat/chat-input.md new file mode 100644 index 0000000000000000000000000000000000000000..52ec3284ece8f4cae9e737d3d2c1c14ee57a0b1a --- /dev/null +++ b/data/develop/api-reference/chat/chat-input.md @@ -0,0 +1,17 @@ +--- +title: st.chat_input +slug: /develop/api-reference/chat/st.chat_input +description: st.chat_input displays a chat input widget. +--- + + + +Read the [Build a basic LLM chat app](/develop/tutorials/llms/build-conversational-apps) tutorial to learn how to use `st.chat_message` and `st.chat_input` to build chat-based apps. + + + + + +For an overview of the `st.chat_input` and `st.chat_message` API, check out this video tutorial by Chanin Nantasenamat ([@dataprofessor](https://www.youtube.com/dataprofessor)), a Senior Developer Advocate at Streamlit. + + diff --git a/data/develop/api-reference/chat/chat-message.md b/data/develop/api-reference/chat/chat-message.md new file mode 100644 index 0000000000000000000000000000000000000000..7bdc31589449b7a61a47afc4eb2c8d5eb301affb --- /dev/null +++ b/data/develop/api-reference/chat/chat-message.md @@ -0,0 +1,17 @@ +--- +title: st.chat_message +slug: /develop/api-reference/chat/st.chat_message +description: st.chat_message inserts a chat message container into the app. +--- + + + +Read the [Build a basic LLM chat app](/develop/tutorials/llms/build-conversational-apps) tutorial to learn how to use `st.chat_message` and `st.chat_input` to build chat-based apps. + + + + + +For an overview of the `st.chat_message` and `st.chat_input` API, check out this video tutorial by Chanin Nantasenamat ([@dataprofessor](https://www.youtube.com/dataprofessor)), a Senior Developer Advocate at Streamlit. + + diff --git a/data/develop/api-reference/command-line/_index.md b/data/develop/api-reference/command-line/_index.md new file mode 100644 index 0000000000000000000000000000000000000000..aeab54042f0611914670c33d5a4833a2a5518e13 --- /dev/null +++ b/data/develop/api-reference/command-line/_index.md @@ -0,0 +1,68 @@ +--- +title: Command-line options +slug: /develop/api-reference/cli +--- + +# Command-line interface + +When you install Streamlit, a command-line (CLI) tool gets installed +as well. The purpose of this tool is to run Streamlit apps, change Streamlit configuration options, +and help you diagnose and fix issues. + +To see all of the supported commands: + +```bash +streamlit --help +``` + +### Run Streamlit apps + +```bash +streamlit run your_script.py [-- script args] +``` + +Runs your app. At any time you can stop the server with **Ctrl+c**. + + + +When passing your script some custom arguments, **they must be passed after +two dashes**. Otherwise the arguments get interpreted as arguments to Streamlit +itself. + + + +To see the Streamlit 'Hello, World!' example app, run `streamlit hello`. + +### View Streamlit version + +To see what version of Streamlit is installed, just type: + +```bash +streamlit version +``` + +### View documentation + +```bash +streamlit docs +``` + +Opens the Streamlit documentation (i.e. this website) in a web browser. + +### Clear cache + +```bash +streamlit cache clear +``` + +Clears persisted files from the on-disk [Streamlit cache](/develop/api-reference/caching-and-state), if +present. + +### View all configuration options + +As described in [Configuration](/develop/concepts/configuration), Streamlit has several +configuration options. To view them all, including their current values, just type: + +```bash +streamlit config show +``` diff --git a/data/develop/api-reference/command-line/run.md b/data/develop/api-reference/command-line/run.md new file mode 100644 index 0000000000000000000000000000000000000000..0bcb7cd57f674d075df695c831e1b3e883056115 --- /dev/null +++ b/data/develop/api-reference/command-line/run.md @@ -0,0 +1,74 @@ +--- +title: streamlit run +slug: /develop/api-reference/cli/run +--- + +## `$ streamlit run` + +### Syntax + +``` +streamlit run [-- config options] [script args] +``` + +### Arguments + +``: The path to your entrypoint file for your Streamlit app. Your entrypoint file is your app's homepage. + +### Options + +Configuration options are passed in the form of `--
.