diff --git a/README.md b/README.md index 066c3eae9..cb5000db1 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,7 @@ We support syntax highlighting for Python, Bash, TOML, SQL, and JSX. Use standard Markdown to link to other pages in the docs. E.g. Add an inline link to the "Create an app" page by including the slug defined in the front matter of the "Create an app" `.md` file: ```markdown -Learn how to [Create an app](/library/get-started/create-an-app). +Learn how to [Create an app](/get-started/tutorials/create-an-app). ``` **Add images:** @@ -242,13 +242,13 @@ However, a user has to know the URL to visit the page. The page is therefore _re How do you make the page you created appear in the Menu? Edit the special markdown file `content/menu.md`. All it has is front matter in YAML. -Suppose you have created an "Installation" page that is available at `docs.streamlit.io/library/get-started/installation`. You want to it to appear in the Menu within the "Streamlit Library" section, nested under the "Get Started" page. +Suppose you have created an "Quickstart" page that is available at `docs.streamlit.io/get-started/installation/quickstart`. You want to it to appear in the Menu within the "Get started" section, nested under the "Installation" page. To do so, find the lines that define the `category`, `url` and `visible` properties for "Get Started" in `menu.md` and add three new lines below it, containing: ```YAML -- category: Streamlit Library / Get Started / Installation - url: /library/get-started/installation +- category: Get Started / Installation / Quickstart + url: /get-started/installation/quickstart visible: true ``` diff --git a/components/blocks/iconHeader.js b/components/blocks/iconHeader.js index 16f8a7530..0a8d41759 100644 --- a/components/blocks/iconHeader.js +++ b/components/blocks/iconHeader.js @@ -6,34 +6,44 @@ const IconHeader = ({ icon, rotate, title, background, color }) => { return (
{icon} -

+

{title}

); }; +const BG_CLASS = { + "red-70": styles.RedBackground, + "orange-70": styles.OrangeBackground, + "yellow-70": styles.YellowBackground, + "green-70": styles.GreenBackground, + "acqua-70": styles.AcquaBackground, + "lightBlue-70": styles.LightBlueBackground, + "darkBlue-70": styles.DarkBlueBackground, + "indigo-70": styles.IndigoBackground, + "gray-70": styles.GrayBackground, + unset: styles.TransparentBackground, +}; + +const FG_CLASS = { + "red-70": styles.RedForeground, + "orange-70": styles.OrangeForeground, + "yellow-70": styles.YellowForeground, + "green-70": styles.GreenForeground, + "acqua-70": styles.AcquaForeground, + "lightBlue-70": styles.LightBlueForeground, + "darkBlue-70": styles.DarkBlueForeground, + "indigo-70": styles.IndigoForeground, + "gray-70": styles.GrayForeground, + unset: styles.TransparentForeground, +}; + export default IconHeader; diff --git a/components/blocks/iconHeader.module.css b/components/blocks/iconHeader.module.css index e2f53ff5c..38ace3bbf 100644 --- a/components/blocks/iconHeader.module.css +++ b/components/blocks/iconHeader.module.css @@ -12,30 +12,70 @@ } /* Color modifiers */ -.VioletBackground { - @apply bg-indigo-70; +.RedBackground { + @apply bg-red-70; } .OrangeBackground { @apply bg-orange-70; } +.YellowBackground { + @apply bg-yellow-70; +} + +.GreenBackground { + @apply bg-green-70; +} + +.AcquaBackground { + @apply bg-acqua-70; +} + .LightBlueBackground { @apply bg-lightBlue-70; } -.VioletText { - @apply text-indigo-70 !important; +.DarkBlueBackground { + @apply bg-darkBlue-70; +} + +.IndigoBackground { + @apply bg-indigo-70; +} + +.RedForeground { + @apply text-red-70 !important; } -.OrangeText { +.OrangeForeground { @apply text-orange-70 !important; } -.LightBlueText { +.YellowForeground { + @apply text-yellow-70 !important; +} + +.GreenForeground { + @apply text-green-70 !important; +} + +.AcquaForeground { + @apply text-acqua-70 !important; +} + +.LightBlueForeground { @apply text-lightBlue-70 !important; } -:global(.dark) .VioletText { +.DarkBlueForeground { + @apply text-darkBlue-70 !important; +} + +.IndigoForeground { + @apply text-indigo-70 !important; +} + +:global(.dark) .IndigoText { @apply text-white !important; } diff --git a/components/blocks/inlineCallout.js b/components/blocks/inlineCallout.js index 841c98dc6..a8b635d22 100644 --- a/components/blocks/inlineCallout.js +++ b/components/blocks/inlineCallout.js @@ -4,18 +4,8 @@ import classNames from "classnames"; import styles from "./inlineCallout.module.css"; const InlineCallout = ({ children, icon, color, bold, href }) => { - const backgroundColor = - color === "violet-70" - ? styles.LibraryBackground - : color === "l-blue-70" - ? styles.CloudBackground - : styles.KBBackground; - const textColor = - color === "violet-70" - ? styles.LibraryText - : color === "l-blue-70" - ? styles.CloudText - : styles.KBText; + const backgroundColor = BG_CLASS[color]; + const textColor = FG_CLASS[color]; return (
{ ); }; +const BG_CLASS = { + "red-70": styles.RedBackground, + "orange-70": styles.OrangeBackground, + "yellow-70": styles.YellowBackground, + "green-70": styles.GreenBackground, + "acqua-70": styles.AcquaBackground, + "lightBlue-70": styles.LightBlueBackground, + "darkBlue-70": styles.DarkBlueBackground, + "indigo-70": styles.IndigoBackground, + "gray-70": styles.GrayBackground, + unset: styles.TransparentBackground, +}; + +const FG_CLASS = { + "red-70": styles.RedForeground, + "orange-70": styles.OrangeForeground, + "yellow-70": styles.YellowForeground, + "green-70": styles.GreenForeground, + "acqua-70": styles.AcquaForeground, + "lightBlue-70": styles.LightBlueForeground, + "darkBlue-70": styles.DarkBlueForeground, + "indigo-70": styles.IndigoForeground, + "gray-70": styles.GrayForeground, + unset: styles.TransparentForeground, +}; + export default InlineCallout; diff --git a/components/blocks/inlineCallout.module.css b/components/blocks/inlineCallout.module.css index 008675e00..b6ad8f5b7 100644 --- a/components/blocks/inlineCallout.module.css +++ b/components/blocks/inlineCallout.module.css @@ -29,26 +29,70 @@ } /* Colors for each category */ -.LibraryBackground { - @apply bg-indigo-70; +.RedBackground { + @apply bg-red-70; +} + +.OrangeBackground { + @apply bg-orange-70; } -.CloudBackground { +.YellowBackground { + @apply bg-yellow-70; +} + +.GreenBackground { + @apply bg-green-70; +} + +.AcquaBackground { + @apply bg-acqua-70; +} + +.LightBlueBackground { @apply bg-lightBlue-70; } -.KBBackground { - @apply bg-orange-70; +.DarkBlueBackground { + @apply bg-darkBlue-70; +} + +.IndigoBackground { + @apply bg-indigo-70; +} + +.RedForeground { + @apply text-red-70; +} + +.OrangeForeground { + @apply text-orange-70; +} + +.YellowForeground { + @apply text-yellow-70; +} + +.GreenForeground { + @apply text-green-70; +} + +.AcquaForeground { + @apply text-acqua-70; +} + +.LightBlueForeground { + @apply text-lightBlue-70; } -.LibraryText { - @apply text-indigo-70 !important; +.DarkBlueForeground { + @apply text-darkBlue-70; } -.CloudText { - @apply text-lightBlue-70 !important; +.IndigoForeground { + @apply text-indigo-70; } -.KBText { - @apply text-orange-70 !important; +:global(.dark) .GrayText { + @apply text-gray-20 !important; } diff --git a/components/blocks/note.js b/components/blocks/note.js index d68c363e7..5421ecb77 100644 --- a/components/blocks/note.js +++ b/components/blocks/note.js @@ -13,7 +13,7 @@ const Note = ({ children }) => { icon="push_pin" rotate="45" title="Note" - background="l-blue-70" + background="lightBlue-70" color="white" /> {children} diff --git a/components/blocks/tile.js b/components/blocks/tile.js index d062b16bb..c0d85af0e 100644 --- a/components/blocks/tile.js +++ b/components/blocks/tile.js @@ -53,14 +53,7 @@ const Tile = ({ ); } - const backgroundColor = - background === "orange-70" - ? styles.OrangeBackground - : background === "violet-70" - ? styles.VioletBackground - : background === "unset" - ? styles.TransparentBackground - : styles.BlueBackground; + const backgroundColor = BG_CLASS[background]; return (
{ icon="star" rotate="0" title="Tip" - background="violet-70" + background="indigo-70" color="white" /> {children} diff --git a/components/layouts/inlineCalloutContainer.js b/components/layouts/inlineCalloutContainer.js index 46f726ca8..dbc39ed8a 100644 --- a/components/layouts/inlineCalloutContainer.js +++ b/components/layouts/inlineCalloutContainer.js @@ -1,7 +1,9 @@ import styles from "./inlineCalloutContainer.module.css"; -const InlineCalloutContainer = ({ children }) => { - return
{children}
; +const InlineCalloutContainer = ({ children, spacing }) => { + const spacingClass = spacing ? styles.SingletonContainer : styles.Container; + + return
{children}
; }; export default InlineCalloutContainer; diff --git a/components/layouts/inlineCalloutContainer.module.css b/components/layouts/inlineCalloutContainer.module.css index 69a3ae240..09f14489a 100644 --- a/components/layouts/inlineCalloutContainer.module.css +++ b/components/layouts/inlineCalloutContainer.module.css @@ -5,3 +5,11 @@ .Container > section:last-child { @apply border-none mb-8 pb-0; } + +.SingletonContainer { + @apply mt-6 mb-6; +} + +.SingletonContainer > section:last-child { + @apply border-none mb-8 pb-0; +} diff --git a/components/layouts/tileContainer.js b/components/layouts/tileContainer.js index 77c3a5ba0..df86cd8f7 100644 --- a/components/layouts/tileContainer.js +++ b/components/layouts/tileContainer.js @@ -1,7 +1,10 @@ import styles from "./tileContainer.module.css"; -const TilesContainer = ({ children }) => { - return
{children}
; +const TilesContainer = ({ layout, children }) => { + const classes = + layout == "list" ? styles.ListContainer : styles.GridContainer; + + return
{children}
; }; export default TilesContainer; diff --git a/components/layouts/tileContainer.module.css b/components/layouts/tileContainer.module.css index 767615fae..70263c60f 100644 --- a/components/layouts/tileContainer.module.css +++ b/components/layouts/tileContainer.module.css @@ -1,3 +1,7 @@ -.Container { +.GridContainer { @apply grid grid-cols-6 gap-4 mb-12; } + +.ListContainer { + @apply flex flex-col gap-4 mb-12; +} diff --git a/components/navigation/navChild.js b/components/navigation/navChild.js index cfef978a9..8582a7e3b 100644 --- a/components/navigation/navChild.js +++ b/components/navigation/navChild.js @@ -122,11 +122,7 @@ const NavChild = ({ slug, page, color, className }) => { className={classNames( styles.Circle, active ? styles.ActiveCircle : "", - color === "violet-70" - ? styles.LibraryCircle - : color === "l-blue-70" - ? styles.CloudCircle - : styles.KBCircle + CIRCLE_CLASS[color] )} /> { ); }; +const CIRCLE_CLASS = { + "red-70": styles.RedCircle, + "orange-70": styles.OrangeCircle, + "yellow-70": styles.YellowCircle, + "green-70": styles.GreenCircle, + "acqua-70": styles.AcquaCircle, + "lightBlue-70": styles.LightBlueCircle, + "darkBlue-70": styles.DarkBlueCircle, + "indigo-70": styles.IndigoCircle, + "gray-70": styles.GrayCircle, + unset: styles.TransparentCircle, +}; + export default NavChild; diff --git a/components/navigation/navChild.module.css b/components/navigation/navChild.module.css index 83331c04d..e452a62a9 100644 --- a/components/navigation/navChild.module.css +++ b/components/navigation/navChild.module.css @@ -84,14 +84,34 @@ } /* Colors for circles */ -.LibraryCircle { - @apply bg-indigo-70; +.RedCircle { + @apply bg-red-70; +} + +.OrangeCircle { + @apply bg-orange-70; +} + +.YellowCircle { + @apply bg-yellow-70; +} + +.GreenCircle { + @apply bg-green-70; +} + +.AcquaCircle { + @apply bg-acqua-70; } -.CloudCircle { +.LightBlueCircle { @apply bg-lightBlue-70; } -.KBCircle { - @apply bg-orange-70; +.DarkBlueCircle { + @apply bg-darkBlue-70; +} + +.IndigoCircle { + @apply bg-indigo-70; } diff --git a/components/navigation/navItem.js b/components/navigation/navItem.js index dbe845f3a..04c1f5b68 100644 --- a/components/navigation/navItem.js +++ b/components/navigation/navItem.js @@ -15,13 +15,10 @@ const NavItem = ({ page, slug, condensed, className }) => { let isCondensed = condensed ? condensed : false; // We only want the color to show when we're either active, or the menu is condensed. - let color = - page.color === "violet-70" - ? styles.LibraryCategory - : page.color === "l-blue-70" - ? styles.CloudCategory - : styles.KBCategory; - color = isCondensed || active ? color : ""; + let fgColor = FG_CLASS[page.color]; + fgColor = isCondensed || active ? fgColor : ""; + + const bgColor = BG_CLASS[page.color]; navBox = (
{ className={classNames( styles.HeadingIconContainer, isCondensed ? styles.CondensedHeadingIconContainer : "", - page.color === "violet-70" - ? styles.LibraryIcon - : page.color === "l-blue-70" - ? styles.CloudIcon - : styles.KBIcon + bgColor )} > {page.icon} @@ -47,7 +40,7 @@ const NavItem = ({ page, slug, condensed, className }) => { className={classNames( styles.CategoryName, isCondensed ? styles.CondensedCategoryName : "", - color + fgColor )} > {page.name} @@ -106,4 +99,30 @@ const NavItem = ({ page, slug, condensed, className }) => { return navItem; }; +const BG_CLASS = { + "red-70": styles.RedBackground, + "orange-70": styles.OrangeBackground, + "yellow-70": styles.YellowBackground, + "green-70": styles.GreenBackground, + "acqua-70": styles.AcquaBackground, + "lightBlue-70": styles.LightBlueBackground, + "darkBlue-70": styles.DarkBlueBackground, + "indigo-70": styles.IndigoBackground, + "gray-70": styles.GrayBackground, + unset: styles.TransparentBackground, +}; + +const FG_CLASS = { + "red-70": styles.RedForeground, + "orange-70": styles.OrangeForeground, + "yellow-70": styles.YellowForeground, + "green-70": styles.GreenForeground, + "acqua-70": styles.AcquaForeground, + "lightBlue-70": styles.LightBlueForeground, + "darkBlue-70": styles.DarkBlueForeground, + "indigo-70": styles.IndigoForeground, + "gray-70": styles.GrayForeground, + unset: styles.TransparentForeground, +}; + export default NavItem; diff --git a/components/navigation/navItem.module.css b/components/navigation/navItem.module.css index 5e8f4dcb5..1ba8c03a4 100644 --- a/components/navigation/navItem.module.css +++ b/components/navigation/navItem.module.css @@ -19,16 +19,36 @@ } /* Colors for heading icons */ -.LibraryIcon { - @apply bg-indigo-70; +.RedBackground { + @apply bg-red-70; +} + +.OrangeBackground { + @apply bg-orange-70; +} + +.YellowBackground { + @apply bg-yellow-70; } -.CloudIcon { +.GreenBackground { + @apply bg-green-70; +} + +.AcquaBackground { + @apply bg-acqua-70; +} + +.LightBlueBackground { @apply bg-lightBlue-70; } -.KBIcon { - @apply bg-orange-70; +.DarkBlueBackground { + @apply bg-darkBlue-70; +} + +.IndigoBackground { + @apply bg-indigo-70; } .CategoryName { @@ -45,16 +65,36 @@ } /* Colors for active categories */ -.LibraryCategory { - @apply text-indigo-70 !important; +.RedForeground { + @apply text-red-70; +} + +.OrangeForeground { + @apply text-orange-70; +} + +.YellowForeground { + @apply text-yellow-70; +} + +.GreenForeground { + @apply text-green-70; +} + +.AcquaForeground { + @apply text-acqua-70; +} + +.LightBlueForeground { + @apply text-lightBlue-70; } -.CloudCategory { - @apply text-lightBlue-70 !important; +.DarkBlueForeground { + @apply text-darkBlue-70; } -.KBCategory { - @apply text-orange-70 !important; +.IndigoForeground { + @apply text-indigo-70; } /* Subnav styles */ diff --git a/components/navigation/sideBar.module.css b/components/navigation/sideBar.module.css index 2068ece5e..4210f013b 100644 --- a/components/navigation/sideBar.module.css +++ b/components/navigation/sideBar.module.css @@ -1,5 +1,11 @@ .Container { - @apply fixed lg:sticky top-auto lg:top-12 left-0 xl:left-auto px-0 h-screen z-20 w-10/12 md:w-9/12 xl:w-screen max-w-xs md:max-w-none overflow-y-auto shadow-lg lg:shadow-none transition-all; + @apply fixed lg:sticky; + @apply top-auto lg:top-12 left-0 xl:left-auto; + @apply px-0 pb-64 h-screen z-20; + @apply w-10/12 md:w-9/12 xl:w-screen max-w-xs md:max-w-none; + @apply overflow-y-auto; + @apply shadow-lg lg:shadow-none; + @apply transition-all; @apply bg-white !important; } diff --git a/components/summaryTiles.js b/components/summaryTiles.js index ddfdf5e71..c09598c41 100644 --- a/components/summaryTiles.js +++ b/components/summaryTiles.js @@ -5,18 +5,18 @@ const SummaryTiles = () => { return ( @@ -24,7 +24,7 @@ const SummaryTiles = () => { icon="grid_view" title="App gallery" text="Try out awesome apps created by our users, and curated from our forums or Twitter." - background="orange-70" + background="lightBlue-70" link="https://streamlit.io/gallery" /> diff --git a/content/get-started/fundamentals/additional-features.md b/content/get-started/fundamentals/additional-features.md new file mode 100644 index 000000000..9d132fd82 --- /dev/null +++ b/content/get-started/fundamentals/additional-features.md @@ -0,0 +1,121 @@ +--- +title: Additional Streamlit features +slug: /get-started/fundamentals/additional-features +--- + +# Additional Streamlit features + +So you've read all about Streamlit's [Main concepts](/get-started/fundamentals/main-concepts) and gotten a tase of caching and Session State in [Advanced concepts](/get-started/fundamentals/advanced-concepts). But what about the bells and whistles? Here's a quick look at some extra features to take your app to the next level. + +## Theming + +Streamlit supports Light and Dark themes out of the box. Streamlit will first +check if the user viewing an app has a Light or Dark mode preference set by +their operating system and browser. If so, then that preference will be used. +Otherwise, the Light theme is applied by default. + +You can also change the active theme from "⋮" → "Settings". + +![Changing Themes](/images/change_theme.gif) + +Want to add your own theme to an app? The "Settings" menu has a theme editor +accessible by clicking on "Edit active theme". You can use this editor to try +out different colors and see your app update live. + +![Editing Themes](/images/edit_theme.gif) + +When you're happy with your work, themes can be saved by +[setting config options](/library/advanced-features/configuration#set-configuration-options) +in the `[theme]` config section. After you've defined a theme for your app, it +will appear as "Custom Theme" in the theme selector and will be applied by +default instead of the included Light and Dark themes. + +More information about the options available when defining a theme can be found +in the [theme option documentation](/library/advanced-features/theming). + + + +The theme editor menu is available only in local development. If you've deployed your app using +Streamlit Community Cloud, the "Edit active theme" button will no longer be displayed in the "Settings" +menu. + + + + + +Another way to experiment with different theme colors is to turn on the "Run on save" option, edit +your config.toml file, and watch as your app reruns with the new theme colors applied. + + + +## Pages + +As apps grow large, it becomes useful to organize them into multiple pages. This makes the app easier to manage as a developer and easier to navigate as a user. Streamlit provides a frictionless way to create multipage apps. + +We designed this feature so that building a multipage app is as easy as building a single-page app! Just add more pages to an existing app as follows: + +1. In the folder containing your main script, create a new `pages` folder. Let’s say your main script is named `main_page.py`. +2. Add new `.py` files in the `pages` folder to add more pages to your app. +3. Run `streamlit run main_page.py` as usual. + +That’s it! The `main_page.py` script will now correspond to the main page of your app. And you’ll see the other scripts from the `pages` folder in the sidebar page selector. The pages are listed according to filename (without file extensions and disregarding underscores). For example: + +
+main_page.py + +```python +import streamlit as st + +st.markdown("# Main page 🎈") +st.sidebar.markdown("# Main page 🎈") +``` + +
+ +
+pages/page_2.py + +```python +import streamlit as st + +st.markdown("# Page 2 ❄️") +st.sidebar.markdown("# Page 2 ❄️") +``` + +
+ +
+pages/page_3.py + +```python +import streamlit as st + +st.markdown("# Page 3 🎉") +st.sidebar.markdown("# Page 3 🎉") +``` + +
+
+ +Now run `streamlit run main_page.py` and view your shiny new multipage app! + + + +Our documentation on [Multipage apps](/library/advanced-features/multipage-apps) teaches you how to add pages to your app, including how to define pages, structure and run multipage apps, and navigate between pages. Once you understand the basics, [create your first multipage app](/get-started/tutorials/create-a-multipage-app)! + +## Static file serving + +As you learned in Streamlit fundamentals, Streamlit runs a server that clients connect to. That means viewers of your app don't have direct access to the files which are local to your to your app. Most of the time, this doesn't matter because Streamlt commands handle that for you. When you use `st.image()` your Streamlit server will access the file and handle the necessary hosting so your app viewers can see it. However, if you want a direct URL to an image or file you'll need to host it. This requires setting the correct configuration and placing your hosted files in a directory named `static`. For example, your project could look like: + +```bash +your-project/ +├── static/ +│ └── my_hosted-image.png +└── streamlit_app.py +``` + +To learn more, read our guide on [Static file serving](/library/advanced-features/static-file-serving). + +## App testing + +Good development hygeine includes testing your code. Automated testing allows you to write higher quality code, faster! Streamlit has a built-in testing framework that let's you build tests easily. Use your favorite testing framework to run your tests. We like [`pytest`](https://pypi.org/project/pytest/). When you test a Streamlit app, you simulate running the app, declare user input, and inspect the results. You can use GitHub workflows to automate your tests and get instant alerts about breaking changes. Learn more in our guide to [App testing](/library/advanced-features/app-testing). diff --git a/content/get-started/fundamentals/advanced-concepts.md b/content/get-started/fundamentals/advanced-concepts.md new file mode 100644 index 000000000..c17c0fb55 --- /dev/null +++ b/content/get-started/fundamentals/advanced-concepts.md @@ -0,0 +1,127 @@ +--- +title: Advanced concepts of Streamlit +slug: /get-started/fundamentals/advanced-concepts +--- + +# Advanced concepts of Streamlit + +Now that you know how a Streamlit app runs and handles data, let's talk about being efficient. Caching allows you to save the output of a function so you can skip over it on rerun. Session State lets you save information for each user that is preserved between reruns. This not only allows you to avoid unecessary recalculation, but also allows you to create dynamic pages and handle progressive processes. + +## Caching + +The Streamlit cache allows your app to stay performant even when loading data from the web, manipulating large datasets, or performing expensive computations. + +The basic idea behind caching is to store the results of expensive function calls and return the cached result when the same inputs occur again rather than calling the function on subsequent runs. + +To cache a function in Streamlit, you need to decorate it with one of two decorators (`st.cache_data` and `st.cache_resource`): + +```python +@st.cache_data +def long_running_function(param1, param2): + return … +``` + +In this example, decorating `long_running_function` with `@st.cache_data` tells Streamlit that whenever the function is called, it checks two things: + +1. The values of the input parameters (in this case, `param1` and `param2`). +2. The code inside the function. + +If this is the first time Streamlit sees these parameter values and function code, it runs the function and stores the return value in a cache. The next time the function is called with the same parameters and code (e.g., when a user interacts with the app), Streamlit will skip executing the function altogether and return the cached value instead. During development, the cache updates automatically as the function code changes, ensuring that the latest changes are reflected in the cache. + +As mentioned, there are two caching decorators: + +- `st.cache_data` is the recommended way to cache computations that return data: loading a DataFrame from CSV, transforming a NumPy array, querying an API, or any other function that returns a serializable data object (str, int, float, DataFrame, array, list, …). It creates a new copy of the data at each function call, making it safe against [mutations and race conditions](/library/advanced-features/caching#mutation-and-concurrency-issues). The behavior of `st.cache_data` is what you want in most cases – so if you're unsure, start with `st.cache_data` and see if it works! +- `st.cache_resource` is the recommended way to cache global resources like ML models or database connections – unserializable objects that you don’t want to load multiple times. Using it, you can share these resources across all reruns and sessions of an app without copying or duplication. Note that any mutations to the cached return value directly mutate the object in the cache (more details below). + +Streamlit's two caching decorators and their use cases. Use st.cache_data for anything you'd store in a database. Use st.cache_resource for anything you can't store in a database, like a connection to a database or a machine learning model. + +For more information about the Streamlit caching decorators, their configuration parameters, and their limitations, see [Caching](/library/advanced-features/caching). + +## Session State + +Session State provides a dictionary-like interface where you can save information that is preserved between script reruns. Use `st.session_state` with key or attribute notation to store and recall values. For example, `st.session_state["my_key"]` or `st.session_state.my_key`. Remember that widgets handle thier statefulness all by themselves, so you won't always need to use Session State! + +### What is a session? + +A session is a single instance of viewing an app. If you view an app from two different tabs in your browser, each tab will have its own session. So each viewer of an app will have a Session State tied to their specific view. Streamlit maintains this session as the user interacts with the app. If the user refreshes their browser page or reloads the URL to the app, their Session State resets and they begin again with a new session. + +### Examples of using Session State + +Here's a simple app that counts the number of times the page has been run. Every time you click the button, the script will rerun. + +```python +import streamlit as st + +if "counter" not in st.session_state: + st.session_state.counter = 0 + +st.session_state.counter += 1 + +st.header(f"This page has run {st.session_state.counter} times.") +st.button("Run it again") +``` + +- **First run:** The first time the app runs for each user, Session State is empty. Therefore, a key-value pair is created (`"counter":0`). As the script continues, the counter is immediately incremented (`"counter":1`) and the result is displayed: "This page has run 1 times." When the page has fully rendered, the script has finished and the Streamlit server waits for the user to do something. When that user clicks the button, a rerun begins. + +- **Second run:** Since "counter" is already a key in Session State, it is not reinitialized. As the script continues, the counter is incremented (`"counter":2`) and the result is displayed: "This page has run 2 times." + +There are a few common scenarios where Session State is helpful. As demonstrated above, Session State is used when you have a progressive process that you want to build upon from one rerun to the next. Session State can also be used to prevent recalculation, similar to caching. However, the differences are important: + +- Caching associates stored values to specific functions and inputs. Cached values are accessible to all users across all sessions. +- Session State associates stored values to keys (strings). Values in session state are only available in the single session where it was saved. + +If you have random number generation in your app, you'd likely use Session State. Here's an example where data is generated randomly at the beginning of each session. By saving this random information in Session State, each user gets different random data when they open the app but it won't keep changing on them as they interact with it. If you select different colors with the picker you'll see that the data does not get re-randomized with each rerun. (If you open the app in a new tab to start a new session, you'll see different data!) + +```python +import streamlit as st +import pandas as pd +import numpy as np + +if "df" not in st.session_state: + st.session_state.df = pd.DataFrame(np.random.randn(20, 2), columns=["x", "y"]) + +st.header("Choose a datapoint color") +color = st.color_picker("Color", "#FF0000") +st.divider() +st.scatter_chart(st.session_state.df, x="x", y="y", color=color) +``` + +If you are pulling the same data for all users, you'd likely cache a function that retrieves that data. On the other hand, if you pull data specific to a user, such as querying their personal information, you may want to save that in Session State. That way, the queried data is only available in that one session. + +As mentioned in [Main concepts](/get-started/fundamentals/main-concepts#widgets), Session State is also related to widgets. Widgets are magical and handle statefulness quietly on their own. As an advanced feature however, you can manipulate the value of widgets within your code by assigning keys to them. Any key assigned to a widget becomes a key in Session State tied to the value of the widget. This can be used to manipulate the widget. After you finish understanding the basics of Streamlit, check out our guide on [Widget behavior](/library/advanced-features/widget-behavior) to dig in the details if you're interested. + +## Connections + +As hinted above, you can use `@st.cache_resource` to cache connections. This is the most general solution which allows you to use almost any connection from any Python library. However, Streamlit also offers a convenient way to handle some of the most popular connections, like SQL! `st.connection` takes care of the caching for you so you can enjoy fewer lines of code. Getting data from your database can be as easy as: + +```python +import streamlit as st + +conn = st.connection("my_database") +df = conn.query("select * from my_table") +st.dataframe(df) +``` + +Of course, you may be wondering where your username and password go. Streamlit has a convenient mechanism for [Secrets management](/library/advanced-features/secrets-management). For now, let's just see how `st.connection` works very nicely with secrets. In your local project directory, you can save a `.streamlit/secrets.toml` file. You save your secrets in the toml file and `st.connection` just uses them! For example, if you have an app file `streamlit_app.py` your project directory may look like this: + +```bash +your-LOCAL-repository/ +├── .streamlit/ +│ └── secrets.toml # Make sure to gitignore this! +└── streamlit_app.py +``` + +For the above SQL example, your `secrets.toml` file might look like the following: + +```toml +[connections.my_database] + type="sql" + dialect="mysql" + username="xxx" + password="xxx" + host="example.com" # IP or URL + port=3306 # Port number + database="mydb" # Database name +``` + +Since you don't want to commit your `secrets.toml` file to your repository, you'll need to learn how your host handles secrets when you're ready to publish your app. Each host platform may have a different way for you to pass your secrets. If you use Stramlit Community Cloud for example, each deployed app has a settings menu where you can load your secrets. After you've written an app and are ready to deploy, you can read all about how to [Deploy your app](/streamlit-community-cloud/deploy-your-app) on Community Cloud. diff --git a/content/get-started/fundamentals/index.md b/content/get-started/fundamentals/index.md new file mode 100644 index 000000000..99acd7502 --- /dev/null +++ b/content/get-started/fundamentals/index.md @@ -0,0 +1,22 @@ +--- +title: Fundamentals +slug: /get-started/fundamentals +--- + +# Fundamentals + +Are you new to Streamlit and want the grand tour? If so, you're in the right place! + + + + Learn the fundamental concepts of Streamlit. How is a Streamlit app structured? How does it run? How does it magically get your data on a webpage? + + + + After you understand the rerun logic of Streamlit, learn how to make efficient and dynamic apps with caching and Session State. Get introduced to handling database connections. + + + + Learn about Streamlit's additional features. You don't need to know these concepts for your first app, but check it out to know what's available. + + diff --git a/content/library/get-started/main-concepts.md b/content/get-started/fundamentals/main-concepts.md similarity index 65% rename from content/library/get-started/main-concepts.md rename to content/get-started/fundamentals/main-concepts.md index bff5c2f40..9a90fda92 100644 --- a/content/library/get-started/main-concepts.md +++ b/content/get-started/fundamentals/main-concepts.md @@ -1,9 +1,9 @@ --- -title: Main concepts -slug: /library/get-started/main-concepts +title: Main concepts of Streamlit +slug: /get-started/fundamentals/main-concepts --- -# Main concepts +# Main concepts of Streamlit Working with Streamlit is simple. First you sprinkle a few Streamlit commands into a normal Python script, then you run it with `streamlit run`: @@ -100,7 +100,7 @@ page. ## Display and style data There are a few ways to display data (tables, arrays, data frames) in Streamlit -apps. [Below](/library/get-started/main-concepts#use-magic), you will be introduced to _magic_ +apps. [Below](#use-magic), you will be introduced to _magic_ and [`st.write()`](/library/api-reference/write-magic/st.write), which can be used to write anything from text to tables. After that, let's take a look at methods designed specifically for visualizing data. @@ -425,147 +425,3 @@ for i in range(100): '...and now we\'re done!' ``` - -## Themes - -Streamlit supports Light and Dark themes out of the box. Streamlit will first -check if the user viewing an app has a Light or Dark mode preference set by -their operating system and browser. If so, then that preference will be used. -Otherwise, the Light theme is applied by default. - -You can also change the active theme from "⋮" → "Settings". - -![Changing Themes](/images/change_theme.gif) - -Want to add your own theme to an app? The "Settings" menu has a theme editor -accessible by clicking on "Edit active theme". You can use this editor to try -out different colors and see your app update live. - -![Editing Themes](/images/edit_theme.gif) - -When you're happy with your work, themes can be saved by -[setting config options](/library/advanced-features/configuration#set-configuration-options) -in the `[theme]` config section. After you've defined a theme for your app, it -will appear as "Custom Theme" in the theme selector and will be applied by -default instead of the included Light and Dark themes. - -More information about the options available when defining a theme can be found -in the [theme option documentation](/library/advanced-features/theming). - - - -The theme editor menu is available only in local development. If you've deployed your app using -Streamlit Community Cloud, the "Edit active theme" button will no longer be displayed in the "Settings" -menu. - - - - - -Another way to experiment with different theme colors is to turn on the "Run on save" option, edit -your config.toml file, and watch as your app reruns with the new theme colors applied. - - - -## Caching - -The Streamlit cache allows your app to stay performant even when loading data from the web, manipulating large datasets, or performing expensive computations. - -The basic idea behind caching is to store the results of expensive function calls and return the cached result when the same inputs occur again rather than calling the function on subsequent runs. - -To cache a function in Streamlit, you need to decorate it with one of two decorators (`st.cache_data` and `st.cache_resource`): - -```python -@st.cache_data -def long_running_function(param1, param2): - return … -``` - -In this example, decorating `long_running_function` with `@st.cache_data` tells Streamlit that whenever the function is called, it checks two things: - -1. The values of the input parameters (in this case, `param1` and `param2`). -2. The code inside the function. - -If this is the first time Streamlit sees these parameter values and function code, it runs the function and stores the return value in a cache. The next time the function is called with the same parameters and code (e.g., when a user interacts with the app), Streamlit will skip executing the function altogether and return the cached value instead. During development, the cache updates automatically as the function code changes, ensuring that the latest changes are reflected in the cache. - -As mentioned, there are two caching decorators: - -- `st.cache_data` is the recommended way to cache computations that return data: loading a DataFrame from CSV, transforming a NumPy array, querying an API, or any other function that returns a serializable data object (str, int, float, DataFrame, array, list, …). It creates a new copy of the data at each function call, making it safe against [mutations and race conditions](/library/advanced-features/caching#mutation-and-concurrency-issues). The behavior of `st.cache_data` is what you want in most cases – so if you're unsure, start with `st.cache_data` and see if it works! -- `st.cache_resource` is the recommended way to cache global resources like ML models or database connections – unserializable objects that you don’t want to load multiple times. Using it, you can share these resources across all reruns and sessions of an app without copying or duplication. Note that any mutations to the cached return value directly mutate the object in the cache (more details below). - -Streamlit's two caching decorators and their use cases. Use st.cache_data for anything you'd store in a database. Use st.cache_resource for anything you can't store in a database, like a connection to a database or a machine learning model. - -For more information about the Streamlit caching decorators, their configuration parameters, and their limitations, see [Caching](/library/advanced-features/caching). - -## Pages - -As apps grow large, it becomes useful to organize them into multiple pages. This makes the app easier to manage as a developer and easier to navigate as a user. Streamlit provides a frictionless way to create multipage apps. - -We designed this feature so that building a multipage app is as easy as building a single-page app! Just add more pages to an existing app as follows: - -1. In the folder containing your main script, create a new `pages` folder. Let’s say your main script is named `main_page.py`. -2. Add new `.py` files in the `pages` folder to add more pages to your app. -3. Run `streamlit run main_page.py` as usual. - -That’s it! The `main_page.py` script will now correspond to the main page of your app. And you’ll see the other scripts from the `pages` folder in the sidebar page selector. For example: - -
-main_page.py - -```python -import streamlit as st - -st.markdown("# Main page 🎈") -st.sidebar.markdown("# Main page 🎈") -``` - -
- -
-pages/page_2.py - -```python -import streamlit as st - -st.markdown("# Page 2 ❄️") -st.sidebar.markdown("# Page 2 ❄️") -``` - -
- -
-pages/page_3.py - -```python -import streamlit as st - -st.markdown("# Page 3 🎉") -st.sidebar.markdown("# Page 3 🎉") -``` - -
-
- -Now run `streamlit run main_page.py` and view your shiny new multipage app! - - - -Our documentation on [Multipage apps](/library/get-started/multipage-apps) teaches you how to add pages to your app, including how to define pages, structure and run multipage apps, and navigate between pages. Once you understand the basics, [create your first multipage app](/library/get-started/multipage-apps/create-a-multipage-app)! - -## App model - -Now that you know a little more about all the individual pieces, let's close -the loop and review how it works together: - -1. Streamlit apps are Python scripts that run from top to bottom -1. Every time a user opens a browser tab pointing to your app, the script is - re-executed -1. As the script executes, Streamlit draws its output live in a browser -1. Scripts use the Streamlit cache to avoid recomputing expensive functions, so - updates happen very fast -1. Every time a user interacts with a widget, your script is re-executed and - the output value of that widget is set to the new value during that run. -1. Streamlit apps can contain multiple pages, which are defined in separate - `.py` files in a `pages` folder. - -![The Streamlit app model](/images/app_model.png) diff --git a/content/get-started/fundamentals/summary.md b/content/get-started/fundamentals/summary.md new file mode 100644 index 000000000..36c705951 --- /dev/null +++ b/content/get-started/fundamentals/summary.md @@ -0,0 +1,20 @@ +--- +title: App model summary +slug: /get-started/fundamentals/summary +--- + +# App model summary + +Now that you know a little more about all the individual pieces, let's close +the loop and review how it works together: + +1. Streamlit apps are Python scripts that run from top to bottom. +1. Every time a user opens a browser tab pointing to your app, the script is executed and a new session is starts. +1. As the script executes, Streamlit draws its output live in a browser. +1. Every time a user interacts with a widget, your script is re-executed and Streamlit redraws its output in the brower. + - The output value of that widget matches the new value during that rerun. +1. Scripts use the Streamlit cache to avoid recomputing expensive functions, so updates happen very fast. +1. Session State lets you save information that persists between reruns when you need more than a simple widget. +1. Streamlit apps can contain multiple pages, which are defined in separate `.py` files in a `pages` folder. + +![The Streamlit app model](/images/app_model.png) diff --git a/content/library/get-started/multipage-apps/create-a-multi-page-app.md b/content/get-started/fundamentals/tutorials/create-a-multi-page-app.md similarity index 96% rename from content/library/get-started/multipage-apps/create-a-multi-page-app.md rename to content/get-started/fundamentals/tutorials/create-a-multi-page-app.md index 6fd4190f9..edc4ebd52 100644 --- a/content/library/get-started/multipage-apps/create-a-multi-page-app.md +++ b/content/get-started/fundamentals/tutorials/create-a-multi-page-app.md @@ -1,13 +1,15 @@ --- title: Create a multipage app -slug: /library/get-started/multipage-apps/create-a-multipage-app +slug: /get-started/tutorials/create-a-multipage-app +nextTitle: API Reference +nextLink: /library/api-reference --- # Create a multipage app -In the [last section](/library/get-started/multipage-apps), we learned what it takes to create multipage apps, including how to define pages, structure and run multipage apps, and navigate between pages in the user interface. If you need a refresher, now is a good time to take a look. +In [Additional features](/get-started/fundamentals/additional-features), we introduced multipage apps, including how to define pages, structure and run multipage apps, and navigate between pages in the user interface. You can read more details in our guide to [Multipage apps](/library/advanced-features/multipage-apps) -In this guide, let’s put our understanding of multipage apps to use by converting the familiar `streamlit hello` command to a multipage app! +In this guide, let’s put our understanding of multipage apps to use by converting the previous version of our `streamlit hello` app to a multipage app! ## Motivation @@ -569,6 +571,6 @@ Here are a few resources to help you get started: - Deploy your app for free on Streamlit's [Community Cloud](/streamlit-community-cloud). - Post a question or share your multipage app on our [community forum](https://discuss.streamlit.io/c/streamlit-examples/9). -- Check out our documentation on [multipage apps](/library/get-started/multipage-apps). +- Check out our documentation on [Multipage apps](/library/advanced-features/multipage-apps). - Read through [Advanced features](/library/advanced-features) for things like caching, theming, and adding statefulness to apps. - Browse our [API reference](/library/api-reference/) for examples of every Streamlit command. diff --git a/content/library/get-started/create-an-app.md b/content/get-started/fundamentals/tutorials/create-an-app.md similarity index 97% rename from content/library/get-started/create-an-app.md rename to content/get-started/fundamentals/tutorials/create-an-app.md index e3354afc5..8c03780af 100644 --- a/content/library/get-started/create-an-app.md +++ b/content/get-started/fundamentals/tutorials/create-an-app.md @@ -1,14 +1,11 @@ --- title: Create an app -slug: /library/get-started/create-an-app +slug: /get-started/tutorials/create-an-app --- # Create an app -If you've made it this far, chances are you've -[installed Streamlit](/library/get-started/installation) and -run through the basics in our [Main concepts](/library/get-started/main-concepts) guide. If -not, now is a good time to take a look. +If you've made it this far, chances are you've [installed Streamlit](/get-started/installation) and run through the basics in [Main concepts](/get-started/fundamentals/main-concepts) and [Advanced concepts](/get-started/fundamentals/advanced-concepts). If not, now is a good time to take a look. The easiest way to learn how to use Streamlit is to try things out yourself. As you read through this guide, test each method. As long as your app is running, every time you add a new element to your script and save, Streamlit's UI will ask if you'd like to rerun the app and view the changes. This allows you to work in a fast interactive loop: you write some code, save it, review the output, write some more, and so on, until you're happy with the results. The goal is to use Streamlit to create an interactive app for your data or model and along the way to use Streamlit to review, debug, perfect, and share your code. @@ -198,7 +195,7 @@ st.subheader('Raw data') st.write(data) ``` -In the [Main concepts](/library/get-started/main-concepts) guide you learned that +In the [Main concepts](/get-started/fundamentals/main-concepts) guide you learned that [`st.write`](/library/api-reference/write-magic/st.write) will render almost anything you pass to it. In this case, you're passing in a dataframe and it's rendering as an interactive table. diff --git a/content/get-started/fundamentals/tutorials/index.md b/content/get-started/fundamentals/tutorials/index.md new file mode 100644 index 000000000..263cff96f --- /dev/null +++ b/content/get-started/fundamentals/tutorials/index.md @@ -0,0 +1,17 @@ +--- +title: Tutorials +slug: /get-started/tutorials +--- + +# Tutorials + +If you've just read through our [Main concepts](/get-started/fundamentals/main-concepts) and want to get your hands on Streamlit. Check out these tutorials. Make sure you have [installed Streamlit](/get-started/installation) so you can execute the code yourself. + + + + uses the concepts learned in Fundamentals along with caching to walk through making your first app. + + + walks through the easy steps to add pages to your app. + + diff --git a/content/get-started/index.md b/content/get-started/index.md new file mode 100644 index 000000000..2ae9eee9d --- /dev/null +++ b/content/get-started/index.md @@ -0,0 +1,36 @@ +--- +title: Get started +slug: /get-started +--- + +# Get started + +This Get Started guide explains how Streamlit works, how to install Streamlit on your preferred +operating system, and how to create your first Streamlit app! + + + + helps you set up your development environment. Walk through installing Streamlit on Windows, macOS, or Linux. Alternatively, code right in your browser with GitHub Codespaces. + + + introduces you to Streamlit's data model and development flow. You'll learn what makes Streamlit the most powerful way to build data apps, including the ability to display and style data, draw charts and maps, add interactive widgets, customize app layouts, cache computation, and define themes. + + + walks you through creating apps using core features to fetch and cache data, draw charts, plot information on a map, and use interactive widgets to filter results. + + + if you want to skip past local installation and code right in your browser. This guide uses Streamlit Community Cloud to help you automatically configure a codespace. + + + + diff --git a/content/get-started/installation/anaconda-distribution.md b/content/get-started/installation/anaconda-distribution.md new file mode 100644 index 000000000..73c1aae95 --- /dev/null +++ b/content/get-started/installation/anaconda-distribution.md @@ -0,0 +1,149 @@ +--- +title: Install Streamlit using Anaconda Distribution +slug: /get-started/installation/anaconda-distribution +--- + +# Install Streamlit using Anaconda Distribution + +This page walks you through installing Streamlit locally using Anaconda Distribution. At the end, you'll build a simple "Hello world" app and run it. You can read more about [Getting started with Anaconda Distribution](https://docs.anaconda.com/free/anaconda/getting-started/) in Anaconda's docs. If you prefer to manage your Python environments via command line, check out how to [Install Streamlit using command line](/get-started/installation/command-line). + +## Prerequisites + +1. **A code editor** + + Anaconda Distribution includes Python and basically everything you need to get started. + The only thing left for you to choose is a code editor. + + Our favorite editor is [VS Code](https://code.visualstudio.com/download), which is also what we + use in all our tutorials. + +1. **Knowledge about environment managers** + + Environment managers create virtual environments to isolate Python package installations between + projects. For a detailed introduction to Python environments, check out + [Python Virtual Environments: A Primer](https://realpython.com/python-virtual-environments-a-primer/). + + But don't worry! In this guide we'll teach you how to install and use an environment manager + (Anaconda). + +## Install Anaconda Distribution + +1. Go to [anaconda.com/download](https://www.anaconda.com/download). + +2. Install Anaconda Distribution for your OS. + +## Create an environment using Anaconda Navigator + +3. Open Anaconda Navigator (the graphical interface included with Anaconda Distribution). + +4. You can decline signing in to Anaconda if prompted. + +5. In the left menu, click "**Environments**". + ![Open your environments list in Anaconda Navigator](/images/get-started/Anaconda-Navigator-environment-1.png) + +6. At the bottom of your environments list, click "**Create**". + ![Click "Create" to open the Create new environment dialog](/images/get-started/Anaconda-Navigator-environment-2-create.png) + +7. Enter "streamlitenv" for the name of your environment. + +8. Click "**Create**." +
+ Finalize your new conda environment +
+ +## Activate your environment + +9. Click the green play icon (play_circle) next to your environment. + +10. Click "**Open Terminal**." + ![Open a new terminal with your environment activated](/images/get-started/Anaconda-Navigator-environment-6-activate.png) + +11. A terminal will open with your environment activated. Your environment's name will appear in parentheses at the beginning of your terminal's prompt to show that it's activated. + +## Install Streamlit in your environment + +12. In your terminal, type: + + ```bash + pip install streamlit + ``` + +13. To validate your installation, enter: + + ```bash + streamlit hello + ``` + + If this doesn't work, use the long-form command: + + ```bash + python -m streamlit hello + ``` + +14. The Streamlit Hello example app will automatically open in your browser. If it doesn't, open your browser and go to the localhost address indicated in your terminal, typically `http://localhost:8501`. Play around with the app! + +15. Close your terminal. + +## Create a `Hello World` app and run it + +17. Open VS Code with a new project. + +18. Create a Python file named `app.py` in your project folder. + ![Create a new file called app.py](/images/get-started/hello-world-1-new-file.png) + +19. Copy the following code into `app.py` and save it. + + ```python + import streamlit as st + + st.write("Hello World") + ``` + +20. Click your Python interpreter in the lower-right corner, then choose your `streamlitenv` environment from the drop-down. + ![Set your Python interpreter to your `streamlitenv` environment](/images/get-started/hello-world-3-change-interpreter.png) + +21. Right-click `app.py` in your file navigation and click "**Open in integrated terminal**". + ![Open your terminal in your project folder](/images/get-started/hello-world-4-open-terminal.png) + +22. A terminal will open with your environment activated. Confirm this by looking for "(streamlitenv)" at the beginning of your next prompt. + If it is not there, manually activate your environment with the command: + + ```bash + conda activate streamlitenv + ``` + +23. In your terminal, type: + + ```bash + streamlit run app.py + ``` + + If this doesn't work, use the long-form command: + + ```bash + python -m streamlit run app.py + ``` + + ![Start your Streamlit app with `streamlit run app.py`](/images/get-started/hello-world-5-streamlit-run.png) + +24. Your app will automatically open in your browser. If it doesn't for any reason, open your browser and go to the localhost address indicated in your terminal, typically `http://localhost:8501`. + +25. Change `st.write` to `st.title` and save your file: + + ```python + import streamlit as st + + st.title("Hello World") + ``` + +26. In your browser, click "**Always rerun**" to instantly rerun your app whenever you save a change to your file. + ![Automatically rerun your app when your source file changes](/images/get-started/hello-world-6-always-rerun.png) + +27. Your app will update! Keep making changes and you will see your changes as soon as you save your file. + ![Your app updates when you resave your source file](/images/get-started/hello-world-7-updated-app.png) + +28. When you're done, you can stop your app with `Ctrl+C` in your terminal or just by closing your terminal. + +## What's next? + +Read about our [Main concepts](/get-started/fundamentals/main-concepts) and try out more commands in your app. diff --git a/content/get-started/installation/cloud-quickstart.md b/content/get-started/installation/cloud-quickstart.md new file mode 100644 index 000000000..a8554db65 --- /dev/null +++ b/content/get-started/installation/cloud-quickstart.md @@ -0,0 +1,136 @@ +--- +title: Use Community Cloud to develop with GitHub Codespaces +slug: /get-started/installation/community-cloud +--- + +# Use Community Cloud to develop with GitHub Codespaces + +To use GitHub codespaces for Streamlit development, a properly configured `devcontainer.json` file is needed to set up the environment. Fortunately, Community Cloud is here to help! Although Streamlit Community Cloud is primarily used to deploy and share apps with the rest of the world, we've build in some handy features to make it easy to use GitHub Codespaces. This guide explains how to create a Community Cloud account and use an automated workflow to get you into a GitHub codespace and live-editing a Streamlit app. The automated workflow will fork our Streamlit Hello app to your GitHub account, deploy it, then open up a codespace for you to start editing. All this happens right in your browser, no installation required. + +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](/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](/streamlit-community-cloud/deploy-your-app). + +
+See your deployed Streamlit app +
diff --git a/content/get-started/installation/command-line.md b/content/get-started/installation/command-line.md new file mode 100644 index 000000000..01ff3cf52 --- /dev/null +++ b/content/get-started/installation/command-line.md @@ -0,0 +1,151 @@ +--- +title: Install Streamlit using command line +slug: /get-started/installation/command-line +--- + +# Install Streamlit using command line + +This page will walk you through creating an environment with `venv` and installing Streamlit with `pip`. These are our recommended tools, but if you are familiar with others you can use your favorite ones too. At the end, you'll build a simple "Hello world" app and run it. If you prefer to have a graphical interface to manage your Python environments, check out how to [Install Streamlit using Anaconda Distribution](/get-started/installation/anaconda-distribution). + +## Prerequisites + +As with any programming tool, in order to install Streamlit you first need to make sure your +computer is properly set up. More specifically, you’ll need: + +1. **Python** + + We support [version 3.8 to 3.12](https://www.python.org/downloads/). + +1. **A Python environment manager** (recommended) + + Environment managers create virtual environments to isolate Python package installations between + projects. + + We recommend using virtual environments because installing or upgrading a Python package may + cause unintentional effects on another package. For a detailed introduction to Python + environments, check out + [Python Virtual Environments: A Primer](https://realpython.com/python-virtual-environments-a-primer/). + + For this guide, we'll be using `venv`, which comes with Python. + +1. **A Python package manager** + + Package managers handle installing each of your Python packages, including Streamlit. + + For this guide, we'll be using `pip`, which comes with Python. + +1. **Only on MacOS: Xcode command line tools** + + Download Xcode command line tools using [these instructions](https://mac.install.guide/commandlinetools/4.html) + in order to let the package manager install some of Streamlit's dependencies. + +1. **A code editor** + + Our favorite editor is [VS Code](https://code.visualstudio.com/download), which is also what we use in + all our tutorials. + +## Create an environment using `venv` + +1. Open a terminal and navigate to your project folder. + + ```bash + cd myproject + ``` + +2. In your terminal, type: + + ```bash + python -m venv .venv + ``` + +3. A folder named ".venv" will appear in your project. This directory is where your virtual environment and its dependencies are installed. + +## Activate your environment + +4. In your terminal, activate your environment with one of the following commands, depending on your operating system. + + ```bash + # Windows command prompt + .venv\Scripts\activate.bat + + # Windows PowerShell + .venv\Scripts\Activate.ps1 + + # macOS and Linux + source .venv/bin/activate + ``` + +5. Once activated, you will see your environment name in parentheses before your prompt. "(.venv)" + +## Install Streamlit in your environment + +6. In the terminal with your environment activated, type: + + ```bash + pip install streamlit + ``` + +7. Test that the installation worked by launching the Streamlit Hello example app: + + ```bash + streamlit hello + ``` + + If this doesn't work, use the long-form command: + + ```bash + python -m streamlit hello + ``` + +8. Streamlit's Hello app should appear in a new tab in your web browser! + +9. Close your terminal when you are done. + +## Create a "Hello World" app and run it + +10. Create a file named `app.py` in your project folder. + +```python +import streamlit as st + +st.write("Hello world") +``` + +11. Any time you want to use your new environment, you first need to go to your project folder (where the `.venv` directory lives) and run the command to activate it: + +```bash +# Windows command prompt +.venv\Scripts\activate.bat + +# Windows PowerShell +.venv\Scripts\Activate.ps1 + +# macOS and Linux +source .venv/bin/activate +``` + +12. Once activated, you will see your environment's name in parentheses at the beginning of your terminal prompt. "(.venv)" + +13. Run your Streamlit app. + +```bash +streamlit run app.py +``` + +If this doesn't work, use the long-form command: + +```bash +python -m streamlit run app.py +``` + +14. To stop the Streamlit server, press `Ctrl+C` in the terminal. + +15. When you're done using this environment, return to your normal shell by typing: + +```bash +deactivate +``` + +## What's next? + +Read about our [Main concepts](/get-started/fundamentals/main-concepts) to understand Streamlit's dataflow model. diff --git a/content/get-started/installation/index.md b/content/get-started/installation/index.md new file mode 100644 index 000000000..52dcc4a8e --- /dev/null +++ b/content/get-started/installation/index.md @@ -0,0 +1,55 @@ +--- +title: Installation +slug: /get-started/installation +--- + +# Installation + +There are multiple ways to set up your development environment and install Streamlit. Read below to +understand these options. Developing locally with Python installed on your own computer is the most +common scenario. + +## Summary for experts + +1. Set up your Python development environment. +2. Run: + ```bash + pip install streamlit + ``` +3. Validate the installation by running our Hello app: + ```bash + streamlit hello + ``` +4. Jump to our [Main concepts](/get-started/fundamentals/main-concepts). + +## Installation steps for the rest of us + + + + + +##### Option 1: I'm comfortable with the command line + +Install Streamlit on your own machine using tools like `venv` and `pip`. + + + + + +##### Option 2: I prefer a graphical interface + +Install Streamlit using the Anaconda Distribution graphical user interface. This is also the best +approach if you're on Windows or don't have Python set up. + + + + + +##### Option 3: I'd rather use a cloud-based environment + +Use Streamlit Community Cloud with GitHub Codespaces so you don't have to go through the trouble +of installing Python and setting up an environment. + + + + diff --git a/content/index.md b/content/index.md index bd07b86d8..259e991dc 100644 --- a/content/index.md +++ b/content/index.md @@ -3,9 +3,9 @@ title: Welcome to Streamlit features: - title: Get started body: Lorem ipsum dolor sit amet, consectetur adipiscing elit. - color: violet-70 + color: indigo-70 icon: arrow_forward - url: /library/get-started + url: /get-started image: "" - title: API reference body: Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut @@ -17,7 +17,7 @@ features: - title: Topic guides body: Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia. - color: l-blue-70 + color: lightBlue-70 icon: description url: Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, @@ -29,27 +29,27 @@ whats_new: facilisis sagittis, vitae nibh massa in facilisis et. Pretium eget non cursus purus tempus porta sodales. icon: visibility - url: /library/get-started + url: /get-started image: /img/logo.svg - title: Feature title body: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Eleifend a facilisis sagittis, vitae nibh massa in facilisis et. Pretium eget non cursus purus tempus porta sodales. - url: /library/get-started + url: /get-started icon: visibility image: "" - body: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Eleifend a facilisis sagittis, vitae nibh massa in facilisis et. Pretium eget non cursus purus tempus porta sodales. title: Feature title - url: /library/get-started + url: /get-started image: /img/logo.svg icon: edit - title: Feature title body: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Eleifend a facilisis sagittis, vitae nibh massa in facilisis et. Pretium eget non cursus purus tempus porta sodales. - url: /library/get-started + url: /get-started icon: edit image: "" news: diff --git a/content/kb/index.md b/content/kb/index.md index d1c109eaf..df19be920 100644 --- a/content/kb/index.md +++ b/content/kb/index.md @@ -9,7 +9,7 @@ The knowledge base is a self-serve library of tips, step-by-step tutorials, and - As mentioned in [Development flow](/library/get-started/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). + 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. diff --git a/content/kb/tutorials/deploy/kubernetes.md b/content/kb/tutorials/deploy/kubernetes.md index 58460e6fa..d2c7109c6 100644 --- a/content/kb/tutorials/deploy/kubernetes.md +++ b/content/kb/tutorials/deploy/kubernetes.md @@ -119,7 +119,7 @@ ENTRYPOINT ["./run.sh"] -As mentioned in [Development flow](/library/get-started/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). +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. diff --git a/content/kb/using-streamlit/sanity-checks.md b/content/kb/using-streamlit/sanity-checks.md index 529401be5..a540be79b 100644 --- a/content/kb/using-streamlit/sanity-checks.md +++ b/content/kb/using-streamlit/sanity-checks.md @@ -56,7 +56,7 @@ st.write(st.__version__) ...then call `streamlit run` on your script and make sure it says the same version as above. If not the same version, check out [these -instructions](/library/get-started/installation) for some sure-fire ways to set up your +instructions](/get-started/installation) for some sure-fire ways to set up your environment. ## Check #4: Is your browser caching your app too aggressively? @@ -115,7 +115,7 @@ At line:1 char:1 To resolve this issue, add [Python to the Windows system PATH](https://datatofish.com/add-python-to-windows-path/). -After adding Python to your Windows PATH, you should then be able to follow the instructions in our [Get Started](/library/get-started) section. +After adding Python to your Windows PATH, you should then be able to follow the instructions in our [Get Started](/get-started) section. ## Check #7 [Windows]: Do you need Build Tools for Visual Studio installed? diff --git a/content/kb/using-streamlit/upgrade-version-streamlit.md b/content/kb/using-streamlit/upgrade-version-streamlit.md index d537ab038..08c1bd9bb 100644 --- a/content/kb/using-streamlit/upgrade-version-streamlit.md +++ b/content/kb/using-streamlit/upgrade-version-streamlit.md @@ -5,7 +5,7 @@ slug: /knowledge-base/using-streamlit/how-upgrade-latest-version-streamlit # How do I upgrade to the latest version of Streamlit? -We recommend upgrading to the latest official release of Streamlit so you have access to the newest, cutting-edge features. If you haven't installed Streamlit yet, please read our [Installation guide](/library/get-started/installation). It helps you set up your virtual environment and walks you through installing Streamlit on Windows, macOS, and Linux. Regardless of which package management tool and OS you're using, we recommend running the commands on this page in a virtual environment. +We recommend upgrading to the latest official release of Streamlit so you have access to the newest, cutting-edge features. If you haven't installed Streamlit yet, please read our [Installation guide](/get-started/installation). It helps you set up your virtual environment and walks you through installing Streamlit on Windows, macOS, and Linux. Regardless of which package management tool and OS you're using, we recommend running the commands on this page in a virtual environment. If you've previously installed Streamlit and want to upgrade to the latest version, here's how to do it based on your dependency manager. diff --git a/content/library/advanced-features/app-menu.md b/content/library/advanced-features/app-menu.md index e73e90bc8..fbed9ad0d 100644 --- a/content/library/advanced-features/app-menu.md +++ b/content/library/advanced-features/app-menu.md @@ -23,7 +23,7 @@ You can manually trigger a rerun of your app by clicking "**Rerun**" from the ap ### Settings -With the "**Settings**" option, you can control the appearance of your app while it is running. If viewing the app locally, you can set how your app responds to changes in your source code. See more about development flow in [Main concepts](/library/get-started/main-concepts#development-flow). You can also force your app to appear in wide mode, even if not set within the script using [`st.set_page_config`](/library/api-reference/utilities/st.set_page_config). +With the "**Settings**" option, you can control the appearance of your app while it is running. If viewing the app locally, you can set how your app responds to changes in your source code. See more about development flow in [Main concepts](/get-started/fundamentals/main-concepts#development-flow). You can also force your app to appear in wide mode, even if not set within the script using [`st.set_page_config`](/library/api-reference/utilities/st.set_page_config).
Settings diff --git a/content/library/advanced-features/app-testing/index.md b/content/library/advanced-features/app-testing/index.md index 9b3aed010..4f64bb0bd 100644 --- a/content/library/advanced-features/app-testing/index.md +++ b/content/library/advanced-features/app-testing/index.md @@ -10,16 +10,16 @@ Streamlit app testing enables developers to build and run automated tests. Bring The provided class, AppTest, simulates a running app and provides methods to set up, manipulate, and inspect the app contents via API instead of a browser UI. AppTest provides similar functionality to browser automation tools like Selenium or Playwright, but with less overhead to write and execute tests. Use our testing framework with a tool like [pytest](https://docs.pytest.org/) to execute or automate your tests. A typical pattern is to build a suite of tests for an app to ensure consistent functionality as the app evolves. The tests run locally and/or in a CI environment like GitHub Actions. - + introduces you to the app testing framework and how to execute tests using pytest. Learn how to initialize and run simulated apps, including how to retrieve, manipulate, and inspect app elements. - + explains how to work with secrets and Session State within app tests, including how to test multipage apps. - + puts together the concepts explained above. Check out an app with multiple tests in place. - + is a compact reference summarizing the available syntax. diff --git a/content/library/advanced-features/button-behavior-and-examples.md b/content/library/advanced-features/button-behavior-and-examples.md index 31f06b61a..ffc184b73 100644 --- a/content/library/advanced-features/button-behavior-and-examples.md +++ b/content/library/advanced-features/button-behavior-and-examples.md @@ -9,7 +9,7 @@ slug: /library/advanced-features/button-behavior-and-examples Buttons created with [`st.button`](/library/api-reference/widgets/st.button) do not retain state. They return `True` on the script rerun resulting from their click and immediately return to `False` on the next script rerun. If a displayed element is nested inside `if st.button('Click me'):`, the element will be visible when the button is clicked and disappear as soon as the user takes their next action. This is because the script reruns and the button return value becomes `False`. -In this guide, we will illustrate the use of buttons and explain common misconceptions. Read on to see a variety of examples that expand on `st.button` using [`st.session_state`](/library/api-reference/session-state). [Anti-patterns](#anti-patterns) are included at the end. Go ahead and pull up your favorite code editor so you can `streamlit run` the examples as you read. Check out Streamlit's [Main concepts](/library/get-started/main-concepts) if you haven't run your own Streamlit scripts yet. +In this guide, we will illustrate the use of buttons and explain common misconceptions. Read on to see a variety of examples that expand on `st.button` using [`st.session_state`](/library/api-reference/session-state). [Anti-patterns](#anti-patterns) are included at the end. Go ahead and pull up your favorite code editor so you can `streamlit run` the examples as you read. Check out Streamlit's [Main concepts](/get-started/fundamentals/main-concepts) if you haven't run your own Streamlit scripts yet. ## When to use `if st.button()` diff --git a/content/library/get-started/multipage-apps/index.md b/content/library/advanced-features/multipage-apps.md similarity index 84% rename from content/library/get-started/multipage-apps/index.md rename to content/library/advanced-features/multipage-apps.md index 94419601e..5ec3e9bc8 100644 --- a/content/library/get-started/multipage-apps/index.md +++ b/content/library/advanced-features/multipage-apps.md @@ -1,17 +1,15 @@ --- title: Multipage apps -slug: /library/get-started/multipage-apps +slug: /library/advanced-features/multipage-apps --- # Multipage apps -As apps grow large, it becomes useful to organize them into multiple pages. This makes the app easier to manage as a developer and easier to navigate as a user. Streamlit provides a frictionless way to create multipage apps. Pages are automatically shown in a nice navigation widget inside the app sidebar, and clicking on a page will navigate to the page without reloading the frontend — making app browsing incredibly fast! - -We created a "single-page app" to explore a public Uber dataset for pickups and drop-offs in New York City on the [previous page](/library/get-started/create-an-app). In this guide, let’s learn how to create multipage apps. Once we have a solid foundation on what it takes to create multipage apps, let’s build one for ourselves in the [next section](/library/get-started/multipage-apps/create-a-multipage-app)! +As apps grow large, it becomes useful to organize them into multiple pages. This makes the app easier to manage as a developer and easier to navigate as a user. Streamlit provides a frictionless way to create multipage apps. Pages are automatically shown in a nice navigation widget inside the app sidebar, and clicking on a page will navigate to the page without reloading the frontend — making app browsing incredibly fast! In this guide, let’s learn how to create multipage apps. ## Structuring multipage apps -Let's understand what it takes to create multipage apps — including how to define pages, structure and run multipage apps, and navigate between pages in the user interface. Once you've understood the basics, you can jump right into the [next section](/library/get-started/multipage-apps/create-a-multipage-app) to convert the familiar `streamlit hello` command into a multipage app! +Let's understand what it takes to create multipage apps — including how to define pages, structure and run multipage apps, and navigate between pages in the user interface. Once you've understood the basics, you can jump right into a tutorial to [Create a multipage app](/get-started/tutorials/create-a-multipage-app). ## Run a multipage app @@ -97,7 +95,7 @@ Emojis can be used to make your page names more fun! For example, a file named ` Pages are automatically shown in a nice navigation UI inside the app's sidebar. When you click on a page in the sidebar UI, Streamlit navigates to that page without reloading the entire frontend — making app browsing incredibly fast! -You can also navigate between pages using URLs. Pages have their own URLs, defined by the file's `label`. When multiple files have the same `label`, Streamlit picks the first one (based on the ordering [described above](/library/get-started/multipage-apps#how-pages-are-sorted-in-the-sidebar)). Users can view a specific page by visiting the page's URL. +You can also navigate between pages using URLs. Pages have their own URLs, defined by the file's `label`. When multiple files have the same `label`, Streamlit picks the first one (based on the ordering [described above](#how-pages-are-sorted-in-the-sidebar)). Users can view a specific page by visiting the page's URL. If a user tries to access a URL for a page that does not exist, they will see a modal like the one below, saying the user has requested a page that was not found in the app’s pages/ directory. @@ -105,7 +103,7 @@ If a user tries to access a URL for a page that does not exist, they will see a ## Notes -- Pages support [magic commands](https://docs.streamlit.io/library/api-reference/write-magic/magic). +- Pages support [magic commands](/library/api-reference/write-magic/magic). - Pages support run-on-save. Additionally, when you save a page, this causes a rerun for users currently viewing that exact page. - Adding or deleting a page causes the UI to update immediately. - Updating pages in the sidebar does not rerun the script. @@ -122,7 +120,7 @@ If a user tries to access a URL for a page that does not exist, they will see a st.write(foo.hello) # If page1 already executed, this should write 123 ``` -- Pages share the same [st.session_state](https://docs.streamlit.io/library/advanced-features/session-state): +- Pages share the same [st.session_state](/library/advanced-features/session-state): ```python # page1.py @@ -136,4 +134,4 @@ If a user tries to access a URL for a page that does not exist, they will see a # If page1 already executed, this should write True ``` -You now have a solid understanding of multipage apps. You've learned how to structure apps, define pages, and navigate between pages in the user interface. It's time to [create your first multipage app](/library/get-started/multipage-apps/create-a-multipage-app)! 🥳 +You now have a solid understanding of multipage apps. You've learned how to structure apps, define pages, and navigate between pages in the user interface. It's time to [create your first multipage app](/get-started/tutorials/create-a-multipage-app)! 🥳 diff --git a/content/library/advanced-features/session-state.md b/content/library/advanced-features/session-state.md index a5faf548f..fbefb2f89 100644 --- a/content/library/advanced-features/session-state.md +++ b/content/library/advanced-features/session-state.md @@ -9,7 +9,7 @@ slug: /library/advanced-features/session-state We define access to a Streamlit app in a browser tab as a **session**. For each browser tab that connects to the Streamlit server, a new session is created. Streamlit reruns your script from top to bottom every time you interact with your app. Each reruns takes place in a blank slate: no variables are shared between runs. -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](/library/get-started/multipage-apps). +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](/library/advanced-features/multipage-apps). In this guide, we will illustrate the usage of **Session State** and **Callbacks** as we build a stateful Counter app. diff --git a/content/library/advanced-features/theming.md b/content/library/advanced-features/theming.md index 593b7514a..04df29a85 100644 --- a/content/library/advanced-features/theming.md +++ b/content/library/advanced-features/theming.md @@ -8,7 +8,7 @@ slug: /library/advanced-features/theming In this guide, we provide examples of how Streamlit page elements are affected by the various theme config options. For a more high-level overview of Streamlit themes, see the Themes section of the -[main concepts documentation](/library/get-started/main-concepts#themes). +[main concepts documentation](/get-started/fundamentals/additional-features#themes). Streamlit themes are defined using regular config options: a theme can be set via command line flag when starting your app using `streamlit run` or by @@ -55,7 +55,7 @@ Defines the background color used in the main content area of your app. ## secondaryBackgroundColor This color is used where a second background color is needed for added -contrast. Most notably, it is the sidebar's background color. It is also used +contrast. Most notably, it is the sidebar's background color. It is also used as the background color for most interactive widgets. ![Secondary Background Color](/images/theme_config_options/secondaryBackgroundColor.png) diff --git a/content/library/api/state/state.md b/content/library/api/state/state.md index 56a5e7afa..e6c7bf4fc 100644 --- a/content/library/api/state/state.md +++ b/content/library/api/state/state.md @@ -6,7 +6,7 @@ description: st.session_state is a way to share variables between reruns, for ea # 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](/library/get-started/multipage-apps). +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](/library/advanced-features/multipage-apps). Check out this Session State basics tutorial video by Streamlit Developer Advocate Dr. Marisa Smith to get started: diff --git a/content/library/get-started/index.md b/content/library/get-started/index.md deleted file mode 100644 index 30e76ca6f..000000000 --- a/content/library/get-started/index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Get started -slug: /library/get-started ---- - -# Get started - -This Get Started guide explains how Streamlit works, how to install Streamlit on your preferred -operating system, and how to create your first Streamlit app! - - - - helps you set up your virtual environment and walks you through installing Streamlit on Windows, macOS, and Linux. Regardless of which package management tool and OS you're using, we recommend running the commands on this page in a virtual environment. - - - introduces you to Streamlit's data model and development flow. You'll learn what makes Streamlit the most powerful way to build data apps, including the ability to display and style data, draw charts and maps, add interactive widgets, customize app layouts, cache computation, and define themes. - - - using Streamlit's core features to fetch and cache data, draw charts, plot information on a map, and use interactive widgets, like a slider, to filter results. - - - teaches you how to add pages to your app, including how to define pages, structure and run multipage apps, and navigate between pages. Once you understand the basics, create your first multipage app based on the familiar streamlit hello command! - -

If you want to skip past local installation, try out our Community Cloud Quickstart to quickly fork an app and jump into a codespace to develop in the cloud. Return to Streamlit library Main concepts to learn how to code a Streamlit app.

- - takes you through creating a Streamlit Community Cloud account. Once you have your account, fork and deploy a sample Streamlit app then jump into editing code with GitHub Codespaces. No installation required! - -
- - diff --git a/content/library/get-started/installation.md b/content/library/get-started/installation.md deleted file mode 100644 index 6901d975a..000000000 --- a/content/library/get-started/installation.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Installation -slug: /library/get-started/installation ---- - -# Install Streamlit - - - -### Skip installation! Community Cloud + GitHub Codespaces - -Community Cloud now makes it easy to skip installation and start coding right in your browser with GitHub Codespaces. 🎉 Hop over to our Community Cloud [Quickstart](/streamlit-community-cloud/get-started/quickstart) to create an account, deploy an example app, and jump right into a codespace to start editing. Return to [Main concepts](/library/get-started/main-concepts) to learn all about how Streamlit works. - -You can edit any app you've deployed on Community Cloud with GitHub Codespaces. See [Edit your app with GitHub Codespaces](/streamlit-community-cloud/manage-your-app/edit-your-app#edit-your-app-with-github-codespaces). - - - -## Table of contents - -1. [Prerequisites](#prerequisites) -2. [Install Streamlit on Windows](#install-streamlit-on-windows) -3. [Install Streamlit on macOS/Linux](#install-streamlit-on-macoslinux) - -## Prerequisites - -Before you get started, you're going to need a few things: - -- Your favorite IDE or text editor -- [Python 3.8 - Python 3.12](https://www.python.org/downloads/) -- [PIP](https://pip.pypa.io/en/stable/installation/) - -## Set up your virtual environment - -Regardless of which package management tool you're using, we recommend running -the commands on this page in a virtual environment. This ensures that the dependencies -pulled in for Streamlit don't impact any other Python projects -you're working on. - -Below are a few tools you can use for environment management: - -- [venv](https://docs.python.org/3/library/venv.html) -- [pipenv](https://pipenv-fork.readthedocs.io/en/latest/) -- [poetry](https://python-poetry.org/) -- [virtualenv](https://virtualenv.pypa.io/en/latest/) -- [conda](https://docs.anaconda.com/free/anaconda/getting-started/) - -## Install Streamlit on Windows - -Streamlit's officially-supported environment manager on Windows is [Anaconda Navigator](https://docs.anaconda.com/free/navigator/). - -### Install Anaconda - -If you don't have Anaconda install yet, follow the steps provided on the [Anaconda installation page](https://docs.anaconda.com/free/anaconda/install/windows/). - -### Create a new environment with Streamlit - -Next you'll need to set up your environment. - -1. Follow the steps provided by Anaconda to [set up and manage your environment](https://docs.anaconda.com/free/navigator/getting-started/#navigator-managing-environments) using the Anaconda Navigator. - -2. Select the "▶" icon next to your new environment. Then select "Open terminal": - - !["Open terminal" in Anaconda Navigator](https://i.stack.imgur.com/EiiFc.png) - -3. In the terminal that appears, type: - - ```bash - pip install streamlit - ``` - -4. Test that the installation worked: - - ```bash - streamlit hello - ``` - - Streamlit's Hello app should appear in a new tab in your web browser! - -### Use your new environment - -1. In Anaconda Navigator, open a terminal in your environment (see step 2 above). -2. In the terminal that appears, use Streamlit as usual: - - ```bash - streamlit run myfile.py - ``` - -## Install Streamlit on macOS/Linux - -Streamlit's officially-supported package manager and environment manager for macOS and Linux are [pip](https://pypi.org/project/pip/) and [venv](https://docs.python.org/3/library/venv.html), respectively. `venv` is a part of [The Python Standard Library](https://docs.python.org/3/library/index.html) and comes bundled with your installation of Python. See instructions on how to install and use `pip` below. - -### Install `pip` - -Install `pip`. More details about installing `pip` can be found in [pip's documentation](https://pip.pypa.io/en/stable/installation/#supported-methods). - -On a macOS: - -```bash -python -m ensurepip --upgrade -``` - -On Ubuntu with Python 3: - -```bash -sudo apt-get install python3-pip -``` - -For other Linux distributions, see [How to install PIP for Python](https://www.makeuseof.com/tag/install-pip-for-python/). - -### Install Xcode command line tools on macOS - -On macOS, you'll need to install Xcode command line tools. They are required to compile some of Streamlit's Python dependencies during installation. To install Xcode command line tools, run: - -```bash -xcode-select --install -``` - -### Create a new environment with Streamlit - -1. Navigate to your project folder: - - ```bash - cd myproject - ``` - -2. Create a new virtual environment in that folder and activate that environment: - - ```bash - python -m venv .venv - ``` - - When you run the command above, a directory called `.venv` will appear in `myproject/`. This directory is where your virtual environment and its dependencies are installed. - -3. Install Streamlit in your environment: - - ```bash - pip install streamlit - ``` - -4. Test that the installation worked: - - ```bash - streamlit hello - ``` - - Streamlit's Hello app should appear in a new tab in your web browser! - - - -### Use your new environment - -1. Any time you want to use the new environment, you first need to go to your project folder (where the `.venv` directory lives) and run: - - ```bash - source .venv/bin/activate - ``` - -2. Now you can use Python and Streamlit as usual: - - ```bash - streamlit run myfile.py - ``` - - To stop the Streamlit server, press `ctrl-C`. - -3. When you're done using this environment, type `deactivate` to return to your normal shell. - -Now that you've installed Streamlit, take a few minutes to read through [Main concepts](/library/get-started/main-concepts) to understand Streamlit's data flow model. diff --git a/content/menu.md b/content/menu.md index b9ccd519c..6d08d69f8 100644 --- a/content/menu.md +++ b/content/menu.md @@ -1,25 +1,38 @@ --- site_menu: + - category: Get started + url: /get-started + color: orange-70 + icon: rocket_launch + - category: Get started / Installation + url: /get-started/installation + - category: Get started / Installation / Use command line + url: /get-started/installation/command-line + - category: Get started / Installation / Use Anaconda Distribution + url: /get-started/installation/anaconda-distribution + - category: Get started / Installation / Use GitHub Codespaces + url: /get-started/installation/community-cloud + - category: Get started / Fundamentals + url: /get-started/fundamentals + - category: Get started / Fundamentals / Main concepts + url: /get-started/fundamentals/main-concepts + - category: Get started / Fundamentals / Advanced concepts + url: /get-started/fundamentals/advanced-concepts + - category: Get started / Fundamentals / Additional features + url: /get-started/fundamentals/additional-features + - category: Get started / Fundamentals / Summary + url: /get-started/fundamentals/summary + - category: Get started / Tutorials + url: /get-started/tutorials + - category: Get started / Tutorials / Create an app + url: /get-started/tutorials/create-an-app + - category: Get started / Tutorials / Create a multipage app + url: /get-started/tutorials/create-a-multipage-app + - category: Streamlit library url: /library - color: violet-70 + color: indigo-70 icon: description - - category: Streamlit library / Get started - url: /library/get-started - - category: Streamlit library / Get started / Installation - url: /library/get-started/installation - - category: Streamlit library / Get started / Main concepts - url: /library/get-started/main-concepts - - category: Streamlit library / Get started / Create an app - url: /library/get-started/create-an-app - - category: Streamlit library / Get started / Multipage apps - url: /library/get-started/multipage-apps - - category: Streamlit library / Get started / Multipage apps / Create a multipage app - url: /library/get-started/multipage-apps/create-a-multipage-app - # - category: Streamlit library / Get started / Deploy an app - # url: /library/get-started/deploy-an-app - # - category: Streamlit library / Get started / App gallery - # url: https://streamlit.io/gallery - category: Streamlit library / API reference url: /library/api-reference - category: Streamlit library / API reference / Write and magic @@ -399,6 +412,12 @@ site_menu: url: /library/advanced-features/button-behavior-and-examples - category: Streamlit library / Advanced features / Caching url: /library/advanced-features/caching + - category: Streamlit library / Advanced features / Optimize performance with st.cache + url: /library/advanced-features/st.cache + visible: false + - category: Streamlit library / Advanced features / Experimental cache primitives + url: /library/advanced-features/experimental-cache-primitives + visible: false - category: Streamlit library / Advanced features / Command-line options url: /library/advanced-features/cli - category: Streamlit library / Advanced features / Configuration @@ -411,12 +430,8 @@ site_menu: url: /library/advanced-features/dataframes - category: Streamlit library / Advanced features / Forms url: /library/advanced-features/forms - - category: Streamlit library / Advanced features / Optimize performance with st.cache - url: /library/advanced-features/st.cache - visible: false - - category: Streamlit library / Advanced features / Experimental cache primitives - url: /library/advanced-features/experimental-cache-primitives - visible: false + - category: Streamlit library / Advanced features / Multipage apps + url: /library/advanced-features/multipage-apps - category: Streamlit library / Advanced features / Add statefulness to apps url: /library/advanced-features/session-state - category: Streamlit library / Advanced features / Widget behavior @@ -462,7 +477,7 @@ site_menu: - category: Streamlit Community Cloud url: /streamlit-community-cloud - color: l-blue-70 + color: lightBlue-70 icon: cloud - category: Streamlit Community Cloud / Get started @@ -524,7 +539,7 @@ site_menu: - category: Knowledge base url: /knowledge-base - color: orange-70 + color: darkBlue-70 icon: school - category: Knowledge base / Tutorials url: /knowledge-base/tutorials diff --git a/content/streamlit-cloud/deploy-your-app/secrets-management.md b/content/streamlit-cloud/deploy-your-app/secrets-management.md index 938f23a1f..fc85fd7fa 100644 --- a/content/streamlit-cloud/deploy-your-app/secrets-management.md +++ b/content/streamlit-cloud/deploy-your-app/secrets-management.md @@ -93,9 +93,9 @@ If you need to add or edit your secrets for an app that is already deployed, you 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) -3. A modal will appear. Click "**Secrets**" on the left. +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) -4. 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. +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 diff --git a/content/streamlit-cloud/get-started/create-your-account.md b/content/streamlit-cloud/get-started/create-your-account.md index 07c6a3ed1..7d3c2c8fa 100644 --- a/content/streamlit-cloud/get-started/create-your-account.md +++ b/content/streamlit-cloud/get-started/create-your-account.md @@ -14,9 +14,10 @@ Streamlit Community Cloud accounts have two underlying identities: primary and s ## 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](#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 diff --git a/content/streamlit-cloud/get-started/index.md b/content/streamlit-cloud/get-started/index.md index 794a621e2..5654c5453 100644 --- a/content/streamlit-cloud/get-started/index.md +++ b/content/streamlit-cloud/get-started/index.md @@ -14,20 +14,23 @@ First things first, you need to create your Streamlit Community Cloud account to icon="rocket_launch" title="Quickstart" text="Create your account and deploy an example app as fast as possible. Jump right into coding with GitHub Codespaces." - link="/streamlit-community-cloud/get-started/quickstart" + link="/streamlit-community-cloud/get-started" + background="lightBlue-70" /> -If you're looking for help to build your first Streamlit app, read our [Get started](/library/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. +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/content/streamlit-cloud/index.md b/content/streamlit-cloud/index.md index 7731351e4..f6df7d405 100644 --- a/content/streamlit-cloud/index.md +++ b/content/streamlit-cloud/index.md @@ -9,46 +9,46 @@ Deploy, manage, and share your Streamlit apps with the world in minutes — 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](/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](/library/get-started) in our Streamlit library documentation or [Fork and edit a public app](/streamlit-community-cloud/get-started/fork-and-edit-a-public-app) from our App gallery. Check out [Quickstart](/streamlit-community-cloud/get-started/quickstart) to speed-run you through creating your account, deploying an example app, and editing it using GitHub Codespaces. +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](/streamlit-community-cloud/get-started/fork-and-edit-a-public-app) from our App gallery. Check out [Community Cloud quickstart](/streamlit-community-cloud/get-started) to speed-run you through creating your account, deploying an example app, and editing it using GitHub Codespaces. Create your account and deploy an example app as fast as possible. Jump right into coding with 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. Share or embed your app. Access logs, reboot apps, set favorites, and more. Jump into a GitHub Codespace to edit your app in the cloud. How to use our docs + introduces you to the world of Streamlit! Learn the fundamental + concepts, set up your development environment, and start coding! + + - includes our Get started guide, API reference, and more advanced - features of the core library including caching, theming, and - Streamlit Components. + includes our API reference, and guides to all of Streamlit's + features in the core library including caching, theming, + Streamlit Components, and more! - +