0
# Shiny for Python
1

2
A web development framework that enables building fast, beautiful, and interactive web applications using reactive programming principles. Shiny for Python brings the power of reactive programming from R Shiny to Python, allowing developers to create data-driven web applications with minimal web development knowledge.
3

4
## Package Information
5

6
- **Package Name**: shiny
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install shiny`
10

11
## Core Imports
12

13
```python
14
import shiny
15
from shiny import App, ui, render, reactive
16
from shiny import Inputs, Outputs, Session
17

18
# Type imports for API signatures
19
from typing import Callable, Literal, Mapping, Generator
20
from htmltools import Tag, TagList, TagChild, TagFunction
21
from starlette.requests import Request
22
from pathlib import Path
23
```
24

25
For Express mode (simplified syntax):
26

27
```python
28
from shiny.express import input, output, ui, render
29
```
30

31
## Basic Usage
32

33
### Core Mode Application
34

35
```python
36
from shiny import App, ui, render, Inputs, Outputs, Session
37

38
# Define UI
39
app_ui = ui.page_fluid(
40
    ui.h1("Hello Shiny!"),
41
    ui.input_slider("n", "Number of observations", 0, 100, 20),
42
    ui.output_text_verbatim("txt")
43
)
44

45
# Define server logic
46
def server(input: Inputs, output: Outputs, session: Session):
47
    @output
48
    @render.text
49
    def txt():
50
        return f"The value of n is {input.n()}"
51

52
# Create app
53
app = App(app_ui, server)
54
```
55

56
### Express Mode Application
57

58
```python
59
from shiny.express import input, output, ui, render
60

61
ui.h1("Hello Express Shiny!")
62
ui.input_slider("n", "Number of observations", 0, 100, 20)
63

64
@render.text
65
def txt():
66
    return f"The value of n is {input.n()}"
67
```
68

69
## Architecture
70

71
Shiny for Python follows a reactive programming model with these key concepts:
72

73
- **App**: The main application class that combines UI and server logic
74
- **UI Functions**: Functions that generate HTML elements for the user interface
75
- **Server Function**: Contains the reactive logic and output rendering
76
- **Reactive Values**: Input values that automatically trigger updates when changed
77
- **Reactive Calculations**: Cached computations that depend on reactive values
78
- **Reactive Effects**: Side effects that run when reactive dependencies change
79
- **Render Functions**: Output functions that generate content for display
80
- **Sessions**: Individual user sessions with isolated state
81
- **Modules**: Reusable UI and server components with namespacing
82

83
## Capabilities
84

85
### Application Framework
86

87
Core application class, lifecycle management, and deployment utilities for creating and running Shiny applications.
88

89
```python { .api }
90
class App:
91
    def __init__(
92
        self,
93
        ui: Tag | TagList | Callable[[Request], Tag | TagList] | Path,
94
        server: Callable[[Inputs], None] | Callable[[Inputs, Outputs, Session], None] | None = None,
95
        *,
96
        static_assets: str | Path | Mapping[str, str | Path] | None = None,
97
        bookmark_store: Literal["url", "server", "disable"] = "disable",
98
        debug: bool = False,
99
    ): ...
100

101
def run_app(
102
    app: str | App = "app:app",
103
    host: str = "127.0.0.1",
104
    port: int = 8000,
105
    *,
106
    autoreload_port: int = 0,
107
    reload: bool = False,
108
    reload_dirs: list[str] | None = None,
109
    reload_includes: list[str] | tuple[str, ...] = ("*.py", "*.css", "*.js", "*.html", "*.yml"),
110
    reload_excludes: list[str] | tuple[str, ...] = (".*", "*.pyc"),
111
    ws_max_size: int = 16777216,
112
    log_level: str | None = None,
113
    app_dir: str | None = ".",
114
    factory: bool = False,
115
    launch_browser: bool = False,
116
    dev_mode: bool = True,
117
    **kwargs: object,
118
) -> None: ...
119
```
120

121
[Application Framework](./app.md)
122

123
### Reactive Programming
124

125
Reactive values, calculations, effects, and event handling that form the core of Shiny's reactive system.
126

127
```python { .api }
128
def reactive.value(value: T | None = None, *, read_only: bool = False) -> Value[T]: ...
129
def reactive.calc(fn: Callable[[], T] | None = None, *, session: Session | None = None) -> Calc[T]: ...
130
def reactive.effect(fn: Callable[[], None] | None = None, *, suspended: bool = False, priority: int = 0, session: Session | None = None) -> Effect: ...
131
def reactive.event(*args: Callable[[], object], ignore_none: bool = True, ignore_init: bool = False) -> Callable[[Callable[[], T]], Callable[[], T]]: ...
132
class reactive.ExtendedTask:
133
    def __init__(self, func: Callable[..., Awaitable[T]]): ...
134
    status: Value[Literal["initial", "running", "success", "error", "cancelled"]]
135
    value: Value[T]
136
    error: Value[BaseException]
137
    def invoke(self, *args: object, **kwargs: object) -> None: ...
138
    def cancel(self) -> None: ...
139
    def result(self) -> T: ...
140
```
141

142
[Reactive Programming](./reactive.md)
143

144
### Output Rendering
145

146
Functions for rendering different types of outputs including text, plots, images, tables, and dynamic UI content.
147

148
```python { .api }
149
def render.text(fn: Callable[[], str] | None = None, *, inline: bool = False) -> text: ...
150
def render.plot(fn: Callable[[], object] | None = None, *, alt: str | None = None, width: float | None = None, height: float | None = None, **kwargs: object) -> plot: ...
151
def render.table(fn: Callable[[], object] | None = None, *, index: bool = False, classes: str = "table shiny-table w-auto", **kwargs: object) -> table: ...
152
def render.data_frame(fn: Callable[[], object] | None = None) -> data_frame: ...
153
def render.ui(fn: Callable[[], Tag | TagChild] | None = None) -> ui: ...
154
def render.download(fn: Callable[[], str | bytes] | None = None, *, filename: str | Callable[[], str] | None = None, media_type: str | Callable[[], str] | None = None, **kwargs: object) -> download: ...
155
def render.code(fn: Callable[[], str] | None = None, *, placeholder: bool = True) -> code: ...
156
def render.image(fn: Callable[[], ImgData] | None = None, *, delete_file: bool = False) -> image: ...
157
def render.express(fn: Callable[[], None] | None = None, *, inline: bool = False, container: TagFunction | None = None, **kwargs: object) -> express: ...
158
```
159

160
[Output Rendering](./render.md)
161

162
### User Interface Components
163

164
Comprehensive set of UI functions for building layouts, input controls, output containers, and interactive elements.
165

166
```python { .api }
167
def ui.page_fluid(*args: TagChild, **kwargs: TagAttr) -> Tag: ...
168
def ui.input_text(id: str, label: str, value: str = "", **kwargs: TagAttr) -> Tag: ...
169
def ui.input_slider(id: str, label: str, min: float, max: float, value: float, **kwargs: TagAttr) -> Tag: ...
170
def ui.output_text(id: str, inline: bool = False, **kwargs: TagAttr) -> Tag: ...
171
def ui.card(*args: TagChild, **kwargs: TagAttr) -> Tag: ...
172
def ui.layout_sidebar(sidebar: Sidebar, *args: TagChild, **kwargs: TagAttr) -> Tag: ...
173
```
174

175
[User Interface Components](./ui.md)
176

177
### Session Management
178

179
Session handling, user input/output management, and session utilities for managing application state and user interactions.
180

181
```python { .api }
182
class Session:
183
    def __init__(self, **kwargs: object): ...
184
    def send_custom_message(self, type: str, message: dict[str, object]) -> None: ...
185
    def download(self, id: str, filename: str, media_type: str = "application/octet-stream") -> None: ...
186

187
class Inputs:
188
    def __call__(self) -> dict[str, object]: ...
189
    def __getattr__(self, name: str) -> Callable[[], object]: ...
190

191
class Outputs:
192
    def __setattr__(self, name: str, value: OutputRenderer[object]) -> None: ...
193
```
194

195
[Session Management](./session.md)
196

197
### Express Mode
198

199
Simplified API for building applications with automatic UI collection and streamlined syntax.
200

201
```python { .api }
202
def express.app_opts(
203
    *,
204
    static_assets: str | Path | Mapping[str, str | Path] | None = None,
205
    bookmark_store: Literal["url", "server", "disable"] | None = None,
206
    debug: bool | None = None,
207
) -> None: ...
208
def express.wrap_express_app(file: Path) -> App: ...
209
def express.is_express_app(app: str, app_dir: str | None) -> bool: ...
210
def express.expressify(fn: Callable[..., T]) -> Callable[..., T]: ...
211
def express.output_args(**kwargs: object) -> Callable[[Callable[..., T]], Callable[..., T]]: ...
212
class express.ui.hold:
213
    def __enter__(self) -> TagList: ...
214
    def __exit__(self, *args: object) -> bool: ...
215
```
216

217
[Express Mode](./express.md)
218

219
### Type Definitions and Exceptions
220

221
Type definitions, exception classes, and utility types used throughout the Shiny framework.
222

223
```python { .api }
224
class SafeException(Exception): ...
225
class SilentException(Exception): ...
226
class SilentCancelOutputException(SilentException): ...
227

228
class FileInfo(TypedDict):
229
    name: str
230
    size: int
231
    type: str
232
    datapath: str
233

234
class ImgData(TypedDict):
235
    src: str
236
    width: NotRequired[str | float]
237
    height: NotRequired[str | float]
238
    alt: NotRequired[str]
239
```
240

241
[Types and Exceptions](./types.md)
242

243
## Module System
244

245
Shiny provides a module system for creating reusable components with proper namespacing:
246

247
```python { .api }
248
def module.ui(fn: Callable[[], TagChild]) -> Callable[[str], TagChild]: ...
249
def module.server(fn: Callable[[Inputs, Outputs, Session], None]) -> Callable[[str, Inputs, Outputs, Session], None]: ...
250
def module.current_namespace() -> str | None: ...
251
def module.resolve_id(id: str) -> str: ...
252
```
253

254
## Validation and Utilities
255

256
Utility functions for application validation and debugging:
257

258
```python { .api }
259
def req(*args: object, cancel_output: bool | Literal["progress"] = False) -> None: ...
260
async def reactive.flush() -> None: ...
261
def reactive.isolate() -> Generator[None, None, None]: ...
262
```