pypi-streamlit

1
# Streamlit
2

3
Streamlit is a comprehensive Python web application framework that enables developers to rapidly transform data scripts into interactive, shareable web applications. It provides a simple, declarative API for creating rich user interfaces with widgets like sliders, charts, maps, and data tables, all without requiring frontend development knowledge.
4

5
## Package Information
6

7
- **Package Name**: streamlit
8
- **Language**: Python  
9
- **Installation**: `pip install streamlit`
10

11
## Core Imports
12

13
```python
14
import streamlit as st
15
```
16

17
For custom components:
18

19
```python
20
import streamlit.components.v1 as components
21
```
22

23
Type imports for API signatures:
24

25
```python
26
from typing import Union, List, Dict, Literal, Any, Optional, ContextManager, NoReturn
27
```
28

29
## Basic Usage
30

31
```python
32
import streamlit as st
33
import pandas as pd
34
import numpy as np
35

36
# Set page configuration
37
st.set_page_config(
38
    page_title="My App",
39
    page_icon="🚀",
40
    layout="wide"
41
)
42

43
# Create content
44
st.title("My Streamlit App")
45
st.write("Welcome to my data application!")
46

47
# Display data
48
data = pd.DataFrame({
49
    'x': np.random.randn(100),
50
    'y': np.random.randn(100)
51
})
52

53
st.dataframe(data)
54
st.line_chart(data)
55

56
# Interactive widgets
57
name = st.text_input("Enter your name:")
58
age = st.slider("Select your age:", 0, 100, 25)
59

60
if st.button("Submit"):
61
    st.success(f"Hello {name}, you are {age} years old!")
62
```
63

64
## Architecture
65

66
Streamlit follows an immediate-mode GUI paradigm where:
67

68
- **Scripts run top-to-bottom** on every user interaction
69
- **Session state** persists data across reruns  
70
- **Delta Generator** renders UI elements incrementally
71
- **Caching** optimizes expensive computations
72
- **Component system** enables custom HTML/JavaScript widgets
73

74
The framework handles the complete web stack including automatic UI generation, real-time updates, WebSocket communication, and deployment capabilities.
75

76
## Capabilities
77

78
### Display Elements and Text
79

80
Core functions for displaying text, data, and status messages including titles, headers, markdown, tables, dataframes, JSON, metrics, and various alert types.
81

82
```python { .api }
83
def title(body: str, anchor: str = None) -> DeltaGenerator: ...
84
def header(body: str, anchor: str = None) -> DeltaGenerator: ...
85
def subheader(body: str, anchor: str = None) -> DeltaGenerator: ...
86
def text(body: str) -> DeltaGenerator: ...
87
def markdown(body: str, unsafe_allow_html: bool = False) -> DeltaGenerator: ...
88
def latex(body: str) -> DeltaGenerator: ...
89
def code(body: str, language: str = "python") -> DeltaGenerator: ...
90
def caption(body: str, unsafe_allow_html: bool = False) -> DeltaGenerator: ...
91
def dataframe(data, width: int = None, height: int = None, use_container_width: bool = False) -> DeltaGenerator: ...
92
def table(data) -> DeltaGenerator: ...
93
def json(body) -> DeltaGenerator: ...
94
def metric(label: str, value, delta=None, delta_color: str = "normal") -> DeltaGenerator: ...
95
def success(body: str) -> DeltaGenerator: ...
96
def info(body: str) -> DeltaGenerator: ...
97
def warning(body: str) -> DeltaGenerator: ...
98
def error(body: str) -> DeltaGenerator: ...
99
def exception(exception: Exception) -> DeltaGenerator: ...
100
```
101

102
[Display Elements and Text](./display-elements.md)
103

104
### Input Widgets
105

106
Interactive form controls for user input including buttons, text fields, sliders, selectors, file uploaders, and specialized inputs like date pickers and color choosers.
107

108
```python { .api }
109
def button(label: str, key: str = None, help: str = None, on_click=None, args=None, kwargs=None, type: Literal["primary", "secondary"] = "secondary", disabled: bool = False) -> bool: ...
110
def download_button(label: str, data, file_name: str = None, mime: str = None) -> bool: ...
111
def checkbox(label: str, value: bool = False, key: str = None) -> bool: ...
112
def radio(label: str, options, index: int = 0, key: str = None) -> Any: ...
113
def selectbox(label: str, options, index: int = 0, key: str = None) -> Any: ...
114
def multiselect(label: str, options, default=None, key: str = None) -> List[Any]: ...
115
def slider(label: str, min_value=None, max_value=None, value=None, step=None, key: str = None) -> Any: ...
116
def text_input(label: str, value: str = "", key: str = None, type: str = "default") -> str: ...
117
def number_input(label: str, min_value=None, max_value=None, value=None, step=None, key: str = None) -> Union[int, float]: ...
118
def text_area(label: str, value: str = "", height: int = None, key: str = None) -> str: ...
119
def date_input(label: str, value=None, min_value=None, max_value=None, key: str = None): ...
120
def time_input(label: str, value=None, key: str = None): ...
121
def file_uploader(label: str, type=None, accept_multiple_files: bool = False, key: str = None): ...
122
def camera_input(label: str, key: str = None): ...
123
def color_picker(label: str, value: str = "#000000", key: str = None) -> str: ...
124
```
125

126
[Input Widgets](./input-widgets.md)
127

128
### Layout and Containers
129

130
Functions for organizing content including columns, tabs, expandable sections, forms, and container management for creating sophisticated multi-panel layouts.
131

132
```python { .api }
133
def container() -> DeltaGenerator: ... 
134
def columns(spec) -> List[DeltaGenerator]: ...
135
def tabs(tab_names: List[str]) -> List[DeltaGenerator]: ...
136
def expander(label: str, expanded: bool = False) -> DeltaGenerator: ...
137
def empty() -> DeltaGenerator: ...
138
def form(key: str) -> DeltaGenerator: ...
139
def form_submit_button(label: str = "Submit", help: str = None) -> bool: ...
140
```
141

142
[Layout and Containers](./layout-containers.md)
143

144
### Charts and Media
145

146
Comprehensive visualization and media display capabilities including native chart types, integration with popular plotting libraries, and multimedia content rendering.
147

148
```python { .api }
149
def line_chart(data=None, x: str = None, y: str = None, width: int = None, height: int = None) -> DeltaGenerator: ...
150
def area_chart(data=None, x: str = None, y: str = None, width: int = None, height: int = None) -> DeltaGenerator: ...
151
def bar_chart(data=None, x: str = None, y: str = None, width: int = None, height: int = None) -> DeltaGenerator: ...
152
def pyplot(fig=None, clear_figure: bool = None) -> DeltaGenerator: ...
153
def altair_chart(altair_chart, use_container_width: bool = False) -> DeltaGenerator: ...
154
def vega_lite_chart(spec: dict, use_container_width: bool = False) -> DeltaGenerator: ...
155
def plotly_chart(figure_or_data, use_container_width: bool = False) -> DeltaGenerator: ...
156
def bokeh_chart(figure, use_container_width: bool = False) -> DeltaGenerator: ...
157
def pydeck_chart(pydeck_obj=None, use_container_width: bool = False) -> DeltaGenerator: ...
158
def graphviz_chart(figure_or_dot: Union[str, graphviz.Graph], use_container_width: bool = False) -> DeltaGenerator: ...
159
def map(data=None, zoom: int = None, use_container_width: bool = False) -> DeltaGenerator: ...
160
def image(image, caption: str = None, width: int = None, use_column_width: str = None) -> DeltaGenerator: ...
161
def audio(data, format: str = "audio/wav", start_time: int = 0) -> DeltaGenerator: ...
162
def video(data, format: str = "video/mp4", start_time: int = 0) -> DeltaGenerator: ...
163
```
164

165
[Charts and Media](./charts-media.md)
166

167
### Configuration, Caching, and State Management
168

169
Application configuration, performance optimization through caching decorators, session state management, and utility functions for app lifecycle control.
170

171
```python { .api }
172
def set_page_config(page_title: str = None, page_icon: str = None, layout: str = "centered", initial_sidebar_state: str = "auto") -> None: ...
173
def get_option(key: str): ...
174
def set_option(key: str, value) -> None: ...
175
@cache
176
def cached_function(): ...
177
@experimental_memo
178
def memo_function(): ...
179
@experimental_singleton  
180
def singleton_function(): ...
181
def stop() -> NoReturn: ...
182
def balloons() -> DeltaGenerator: ...
183
def snow() -> DeltaGenerator: ...
184
def progress(value: Union[int, float]) -> DeltaGenerator: ...
185
def spinner(text: str = "In progress...") -> ContextManager[DeltaGenerator]: ...
186
def echo(code_location: str = "above") -> ContextManager[DeltaGenerator]: ...
187
def write(*args, **kwargs) -> DeltaGenerator: ...
188
def help(obj) -> DeltaGenerator: ...
189
def experimental_rerun() -> NoReturn: ...
190
def rerun() -> NoReturn: ...
191
def experimental_get_query_params() -> Dict[str, List[str]]: ...
192
def experimental_set_query_params(**query_params) -> None: ...
193
def experimental_show(*args, **kwargs) -> None: ...
194
def beta_container() -> DeltaGenerator: ...
195
def beta_expander(label: str, expanded: bool = False) -> DeltaGenerator: ...
196
def beta_columns(spec) -> List[DeltaGenerator]: ...
197
```
198

199
[Configuration and Caching](./caching-config.md)
200

201
### Custom Components
202

203
Framework for creating and using custom HTML/JavaScript components, enabling extension of Streamlit's built-in widget set with reusable interactive elements.
204

205
```python { .api }
206
def declare_component(name: str, path: str = None, url: str = None) -> ComponentCallable: ...
207
def html(body: str, width: int = None, height: int = None, scrolling: bool = False) -> None: ...
208
def iframe(src: str, width: int = None, height: int = None, scrolling: bool = False) -> None: ...
209
```
210

211
[Custom Components](./custom-components.md)
212

213
## Core Types and Data Structures
214

215
```python { .api }
216
class DeltaGeneratorProto:
217
    """Protocol for delta generator objects."""
218
    
219
class SessionStateProxy:
220
    """Proxy for session state access."""
221
    def __getitem__(self, key: str) -> Any: ...
222
    def __setitem__(self, key: str, value: Any) -> None: ...
223
    def __contains__(self, key: str) -> bool: ...
224
    def __delitem__(self, key: str) -> None: ...
225

226
class SecretsProxy:
227
    """Proxy for secrets access."""
228
    def __getitem__(self, key: str) -> Any: ...
229
    def __contains__(self, key: str) -> bool: ...
230
    
231
class UserInfoProxy:
232
    """Proxy for user information access (experimental)."""
233
    @property
234
    def email(self) -> str: ...
235

236
# Special variables
237
session_state: SessionStateProxy
238
secrets: SecretsProxy
239
experimental_user: UserInfoProxy
240
sidebar: DeltaGenerator
241
```
242

243
## Error Handling
244

245
Streamlit defines several specialized exceptions for different error conditions:
246

247
```python { .api }
248
class StreamlitAPIException(Exception):
249
    """Base exception for Streamlit API errors."""
250

251
class NoSessionContext(StreamlitAPIException):
252
    """Raised when no session context is available."""
253

254
class DuplicateWidgetID(StreamlitAPIException):
255
    """Raised when duplicate widget keys are used."""
256
```
257

258
Common error patterns:
259
- Widget key conflicts raise `DuplicateWidgetID` exceptions
260
- Missing session context raises `NoSessionContext`
261
- Invalid configuration values raise `StreamlitAPIException`