К основному содержанию
скилл CX Codex

shiny-py-optimize — скилл для Claude Code: ускорение Shiny

Скилл shiny-py-optimize для Claude Code находит и исправляет причины медленной работы приложений Shiny for Python. Включается при зависаниях, долгой загрузке или частых пересчётах.

MIT 116 установок ★ 574 обновлён 2026-10-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add posit-dev/skills --skill shiny-py-optimize -a claude-code
Открыть на GitHub

Что делает shiny-py-optimize

Скилл помогает ускорить существующее приложение Shiny for Python, сохраняя его логику. Он разбирает жалобу на производительность, ищет лишнюю загрузку данных и повторные вычисления, затем предлагает поведенчески безопасные изменения и способы измерить результат.

Среди рекомендуемых приёмов — общие реактивные вычисления, кэширование, отложенная загрузка тяжёлых выводов и @reactive.extended_task для блокирующей работы. Синхронный блокирующий вызов в реактивной функции замораживает все сессии процесса; одного async/await недостаточно, чтобы сохранить отзывчивость той же сессии. Поведение асинхронных реактивных функций зависит от версии Shiny.

Какие задачи решает

  • найти причину медленной первой загрузки
  • сократить повторные реактивные вычисления
  • избежать блокировки сессий синхронными вызовами
  • подготовить приложение к большему числу пользователей

Примеры запросов агенту

  • Найди, почему приложение Shiny for Python медленно загружается, и предложи безопасные исправления.
  • Разбери повторные вычисления в этом приложении Shiny и сократи лишнюю работу.
  • Проверь, какие синхронные вызовы блокируют сессии Shiny for Python.

Как установить shiny-py-optimize

1Через Skills CLI (Vercel)

npx skills add posit-dev/skills --skill shiny-py-optimize -a claude-code

2Вручную: положить файлы

~/.claude/skills/shiny-py-optimize/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/shiny-py-optimize/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о shiny-py-optimize

Как установить shiny-py-optimize в Claude Code?

Выполни npx skills add posit-dev/skills --skill shiny-py-optimize -a claude-code. Файл скилла находится по пути ~/.claude/skills/shiny-py-optimize/SKILL.md.

Что делает shiny-py-optimize?

Ищет причины замедления приложений Shiny for Python и предлагает изменения, которые сохраняют их логику. Также описывает измерение производительности.

Почему синхронный вызов может заморозить приложение Shiny?

Синхронная блокирующая операция в реактивной функции останавливает общий цикл событий процесса, поэтому замерзают все его сессии.

Исходный текст

SKILL.md · MIT
---
name: shiny-py-optimize
description: >
  Diagnose and fix performance problems in Shiny for Python apps — slow
  startup, sluggish interactions, blocking operations, and apps that struggle
  beyond a handful of concurrent users. Use when a Shiny for Python app is
  slow, hangs, recomputes too much, times out, or must support more users;
  when the user asks to "speed up", "optimize", or "make faster" a Python
  Shiny app; or when preparing a prototyped app for real-world traffic.
metadata:
  author: Garrick Aden-Buie (@gadenbuie)
  version: "1.0"
license: MIT
---

# Optimizing Shiny for Python App Performance

Make an existing Shiny for Python app faster without changing what it does.
The typical user has an app that worked fine for one or two developers and is
now too slow or must support more users. Keep all app logic intact; prefer
code changes over deployment tuning; resist rewrites.

Order of preference for every fix:

1. **Eliminate** work that isn't needed (don't compute outputs nobody is
   looking at; don't compute with inputs that aren't ready).
2. **Reuse** work that repeats (shared `@reactive.calc`, module-level caches).
3. **Accelerate** unavoidable work (faster data formats, polars, push-down).
4. **Relocate** work that blocks (`@reactive.extended_task`) — last resort; it
   buys concurrency, not raw speed.

One fact drives most Python-specific advice: **every session in a process
shares one asyncio event loop.** A *synchronous* blocking call in any reactive
function freezes every session in the process. What a slow `async def`
reactive blocks depends on the shiny version (check with
`python -c "import shiny; print(shiny.__version__)"`):

- **shiny < 1.9.0:** reactive functions run serially across the whole
  process, so a slow `async` reactive also freezes every session.
- **shiny ≥ 1.9.0:** effects run concurrently, so a slow `async` reactive
  holds only *its own* session (no input updates, no outputs until it
  finishes); other sessions keep running.

Either way, `async`/`await` alone never keeps the *same* session responsive;
only `@reactive.extended_task` does. And 1.9.0 changes nothing for sync code:
`time.sleep`, pandas, matplotlib drawing, or a sync DB call still freezes
every session on every version. Don't recommend upgrading shiny to fix a
freeze caused by sync work.

## Workflow

### 1. Understand the complaint

Pin down what "slow" means and write it as a benchmark to beat:

- **What feels slow?** First page load? Every interaction? One specific
  action? Only when several people use it at once?
- **How many concurrent users** must it support? (1–5, ~20, hundreds?)
- **Where does it run?** Locally, Posit Connect, Posit Connect Cloud,
  self-hosted (uvicorn behind nginx)?
- **How big is the data**, where does it live, and how often does it change?
- **Core or Express?** (`from shiny import ...` vs `from shiny.express import
  ...`). Express top-level code runs once **per session** — a common silent
  trap (data-loading.md).

### 2. Scan the source for smells — and fix them now

Read the app code (`app.py`, modules) and look for the classic smells. Every
smell in this table has a **safe, behavior-preserving fix**: apply each fix
you find *immediately*, before measuring. These changes fix the large majority
of slow Shiny for Python apps.

| Smell (search for) | Why it hurts | Fix |
|---|---|---|
| `pd.read_csv`/DB queries **inside** `server()` or render functions | Re-runs per session or per invalidation | Load once per process: module scope (Core), imported module (Express) → [data-loading.md](references/data-loading.md) |
| Data loads at **top level of an Express `app.py`** | Top-level Express code runs once **per session** | Move loads into an imported module (`shared.py`) → [data-loading.md](references/data-loading.md) |
| Same subsetting/aggregation repeated in several outputs | Duplicate computation on every change | Extract one shared `@reactive.calc` → [reactive-graph.md](references/reactive-graph.md) |
| Expensive `@render.*` with no `req()` guard | Computes on empty/half-ready inputs at startup | `req()` at the top of the body → [reactive-graph.md](references/reactive-graph.md) |
| Many heavy outputs on the landing view | All must compute before the page is usable | Move to tabs/navs — hidden outputs are suspended → [rendering-ui.md](references/rendering-ui.md) |
| Identical expensive work repeated across sessions | Every user re-pays the same cost | Module-level cache (`functools.lru_cache`, `diskcache`) — there is no built-in `bindCache` equivalent → [caching.md](references/caching.md) |
| Sliders/text inputs feeding expensive chains directly | One drag = dozens of recomputations | `@reactive.event()` button gating; debounce helper → [reactive-graph.md](references/reactive-graph.md) |
| `time.sleep`, sync `requests`, heavy pandas/DuckDB calls inline in calcs/effects/renders | Blocks the event loop for **every user in the process** | `@reactive.extended_task` → [async-tasks.md](references/async-tasks.md) |
| `async def` reactives added expecting a speedup | A slow async reactive still holds its session (and, on shiny < 1.9.0, every session) | Async only for async-only APIs; `ExtendedTask` for non-blocking → [async-tasks.md](references/async-tasks.md) |
| `@render.ui` used for routine value updates | DOM rebuild + input re-binding per update | `ui.update_*()` → [rendering-ui.md](references/rendering-ui.md) |
| `@render.table` on large data frames | pandas Styler → full HTML serialization | `@render.data_frame` with `render.DataGrid` → [rendering-ui.md](references/rendering-ui.md) |

Apply the fixes in this rough order (cheapest first): data loads to module
scope (or imported module in Express) → `req()` guards → shared
`@reactive.calc`s → tabs for heavy outputs → module-level caches →
`@reactive.event()` gating for chatty inputs → `ui.update_*()` over
`@render.ui` → faster data formats (polars, parquet, DuckDB) →
`@reactive.extended_task` for multi-second operations → busy indicators
(`ui.busy_indicators`) for remaining waits.

### 3. Measure — to confirm, not to gate

Measurement is for confirming fixes and for finding what the scan can't see.
**It must never crowd out action.** If the app is hard to run, tracing is
slow, or results are ambiguous, apply the scan fixes anyway and say what
couldn't be verified.

Shiny (≥ 1.6) has built-in OpenTelemetry tracing of reactive execution — the
primary "which code is slow" tool:

```bash
uv pip install "shiny[otel]"
SHINY_OTEL_COLLECT=reactivity \
opentelemetry-instrument --traces_exporter console --logs_exporter console \
    --metrics_exporter none shiny run app.py
```

Interact with the app, then read the span hierarchy: every slow
`reactive.calc` / output / extended task appears with its source file and
line. Use `py-spy` to sample a live process when you need a CPU flame graph,
and `timeit` to compare two implementations. For "how many users can this
app support", load test the deployed app with `shinyloadtest` (record →
replay with N workers → report). Tool selection and reading guides:
[diagnosis.md](references/diagnosis.md).

### 4. Diagnose what the scan didn't catch

| Symptom | Most likely causes | Start here |
|---|---|---|
| First page load is slow (every session) | Per-session data loading (especially Express top-level); outputs computing at startup on empty inputs; heavy per-session setup | [data-loading.md](references/data-loading.md), [reactive-graph.md](references/reactive-graph.md) |
| One interaction recomputes far too much | Over-broad dependencies; duplicate computation; chatty inputs | [reactive-graph.md](references/reactive-graph.md), [caching.md](references/caching.md) |
| A specific action takes seconds and the app freezes — for **everyone** | Sync blocking operation on the shared event loop (or any slow reactive, on shiny < 1.9.0) | [async-tasks.md](references/async-tasks.md) |
| A specific action takes seconds and the app freezes — only for **that user** | Slow `async` reactive holding its session (shiny ≥ 1.9.0) | [async-tasks.md](references/async-tasks.md) |
| Fast for one user, degrades with several | Blocking operations; repeated identical computation; per-user reloads; too few processes | [caching.md](references/caching.md), [async-tasks.md](references/async-tasks.md), [diagnosis.md](references/diagnosis.md) |
| Plots/tables slow to appear or update | Heavy rendering; `@render.table`; full redraws; un-aggregated Plotly | [rendering-ui.md](references/rendering-ui.md) |
| Downloads/uploads misbehave or recompute | Download handler recomputing per click; uploads parsed in renderers | [data-loading.md](references/data-loading.md) |
| Slower only when deployed | Per-process globals and caches; process/connection limits | [diagnosis.md](references/diagnosis.md) |

### 5. Fix, cheapest change first

Work the ladder for the diagnosed category; stop when measurements say it's
fast enough. Every rung preserves app behavior.

**Reactive recomputation** → [reactive-graph.md](references/reactive-graph.md)
1. `req()` guards — nothing computes on not-ready inputs.
2. Shared `@reactive.calc`s — each derived value computed once per change.
3. Narrow dependencies: `@reactive.event()`, `reactive.isolate()`,
   `reactive.value.freeze()` for update loops.
4. Debounce chatty inputs (helper — not built in as of Shiny 1.8); when
   updates compound, gate the batch behind `ui.input_task_button()` (drop-in
   for `ui.input_action_button()`).
5. Fix timers: `invalidate_later()` scheduled **last**, `@reactive.poll()`
   with a cheap check function.

**Repeated identical work** → [caching.md](references/caching.md)
1. `@reactive.calc` memoizes its latest value per session — for free.
2. `@functools.lru_cache` on module-level pure functions (DB queries, model
   fits) — keys must cover **every** input that affects the result.
3. `diskcache`/`cachetools.TTLCache` when results must be shared across
   processes or survive restarts, or the data changes over time.
4. Treat cached results as read-only shared state — return copies before
   mutation.

**Blocking operations** → [async-tasks.md](references/async-tasks.md)
1. Only after elimination/caching are exhausted: `@reactive.extended_task`
   with `ui.input_task_button` + `@ui.bind_task_button`.
2. Sync I/O inside the task → `asyncio.to_thread(...)`; CPU-bound work → a
   module-level `ProcessPoolExecutor` (plain threads won't help CPU work).
3. No reactive reads inside the task body; pass values via `.invoke()`.

**Data access** → [data-loading.md](references/data-loading.md)
1. Loads to process scope (module scope in Core; an imported module in
   Express); never read data in render functions.
2. polars over pandas for anything sizable; parquet over CSV.
3. DuckDB over parquet, or lazy `pl.scan_parquet(...).filter(...).collect()`,
   when data outgrows RAM or only slices are needed.

**Rendering & UI** → [rendering-ui.md](references/rendering-ui.md)
1. Heavy outputs on tabs/navs so hidden outputs stay suspended.
2. Gate speculative outputs behind buttons (`req()` + `@reactive.event()`).
3. `@render.data_frame` + `update_data()` for tables; WebGL/aggregation for
   big Plotly; busy indicators while work runs.

### 6. Verify and iterate

Re-measure after each change, one change at a time, and compare against your
baseline numbers. Keep observable behavior identical — a "faster" app that
dropped a feature is not faster. Before finishing, recompute one
representative output's value from the original and modified apps (or from
the raw data) and confirm they match — this catches silent behavior drift
cheaply.

Report integrity: save every measurement you cite (trace output, timing log)
under `outputs/measurements/` in the app's project — create the folder if it
doesn't exist — and check each number and mechanism claimed in the final
report against those saved artifacts. If a claim can't be verified against
an artifact, say so in the report instead of asserting it.

```
<app-project>/
  outputs/
    measurements/    # the audit trail for the final report: one file per
                     # measurement (trace output, py-spy profile, timings),
                     # named for the fix or code path it measured
```

## Ground rules

- **Batch the obvious; isolate the uncertain.** Safe fixes with predictable
  effects — moving a data load to module scope, consolidating duplicated
  filtering, replacing a `@render.ui` — can be applied together and
  re-measured once. Reach for one-change-at-a-time only when it's genuinely
  unclear which change helped, or a change didn't deliver its expected
  effect; that's the only situation where attribution is worth the extra
  measurement rounds.
- **Preserve behavior.** UI changes are limited to perceived-performance aids
  (spinners, task buttons, tabs) and must be flagged to the user — as must
  changes that alter *timing semantics* even when outputs are identical
  (debouncing adds intentional latency; caches share results across
  sessions).
- **`async` is not a performance fix.** `async def` reactives exist so you can
  call async-only APIs. They do not make the computation faster or keep the
  session responsive. Non-blocking means `@reactive.extended_task`.
- **Caching before async.** Caching often yields 10–100×; async only adds
  concurrency and carries serialization and debugging costs.
- **Never scale with multi-worker servers.** `uvicorn --workers >1`, the
  `WEB_CONCURRENCY` env var, and multi-worker Gunicorn silently break Shiny
  (sticky-session requirement, [diagnosis.md](references/diagnosis.md)).
  Scale with multiple single-worker processes behind sticky-session load
  balancing.
- **Ask before adding dependencies** (polars, duckdb, diskcache, py-spy...).

## References

Read **only** the reference your diagnosis points to, when you need it — do
not read all of them up front.

- [diagnosis.md](references/diagnosis.md) — OpenTelemetry tracing, py-spy,
  timing checks, load testing with shinyloadtest; the single-process asyncio
  model; sticky sessions and deployment capacity knobs.
- [reactive-graph.md](references/reactive-graph.md) — shared calcs, `req()`,
  `reactive.isolate()`, `@reactive.event()`, update loops and
  `reactive.value.freeze()`, the debounce helper, timers and polling.
- [caching.md](references/caching.md) — what `@reactive.calc` does and
  doesn't cache; module-level `lru_cache`/`diskcache`/`cachetools` patterns
  and their hard rules.
- [async-tasks.md](references/async-tasks.md) — why blocking hurts everyone,
  the `@reactive.extended_task` pattern and its hard rules, threads vs
  process pools.
- [data-loading.md](references/data-loading.md) — process-scope loading
  (Core and Express), polars/parquet/DuckDB lazy loading, databases,
  downloads and uploads.
- [rendering-ui.md](references/rendering-ui.md) — output suspension via tabs,
  `@render.ui` alternatives, plot/table rendering costs, perceived
  performance.

© Garrick Aden-Buie (@gadenbuie) · MIT · posit-dev/skills

Похожие скиллы

Каталог скиллов SKILL.md →
vercel-optimize vercel-labs Скилл vercel-optimize для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI, который проводит аудит стоимости и производительности задеплоенных проектов на Vercel. CX Codex +1 136 600установок caveman-optimize JuliusBrussee Скилл caveman-optimize помогает разобрать наблюдение Caveman, выбрать кандидата оператором и проверить его парным сравнением с базовой версией. Изменения требуют явного одобрения. CX Codex +1 129 900установок convex-optimize convex Скилл convex-optimize проводит аудит существующего приложения на Convex и предлагает план правок: безопасность, масштаб, обновления компонентов, наблюдаемость. CX Codex +1 44 000установок az-cost-optimize официальный github Скилл az-cost-optimize анализирует Azure-ресурсы и IaC, ищет варианты снижения затрат и создаёт GitHub issues после подтверждения. Нужен при ревизии расходов проекта в Azure. CX Codex +1 8 700установок optimize-text-mesh-pro Unity-Technologies Скилл optimize-text-mesh-pro для Claude Code разбирает проблемы TextMeshPro с памятью, шрифтами и качеством текста. Он включается при вопросах о TMP, многоязычных надписях или производительности. CX Codex +1 7 200установок optimize-audio Unity-Technologies Скилл optimize-audio проверяет настройки аудио в Unity и помогает найти причины высокого расхода памяти, нагрузки на микшер или проблем с 3D-звуком. CX Codex +1 7 100установок

Из того же набора30

Весь набор →
r-cran-status Скилл r-cran-status проверяет состояние R-пакета на cran.r-project.org: где он в очереди ревью, принят или отклонён, проходит ли R CMD check на всех платформах. CX Codex +1 227установок r-testthat Скилл r-testthat для Claude Code помогает писать и упорядочивать тесты R-пакетов с testthat версии 3 и выше. Агент подключает его при создании тестов или доработке существующих. CX Codex +1 182установок r-tidyverse-style Скилл r-tidyverse-style для Claude Code проверяет и форматирует код пакетов на R по гайдлайну tidyverse. Включается при запросе на ревью оформления или написании нового кода пакета. CX Codex +1 177установок r-cli Скилл r-cli для Claude Code помогает оформлять консольный интерфейс в R-пакетах через библиотеку cli. Включается при замене base R сообщений, настройке прогресс-баров и форматировании ошибок. CX Codex +1 151установок r-lifecycle Скилл r-lifecycle для Claude Code помогает управлять жизненным циклом функций и аргументов в пакетах на R. Ассистент настраивает предупреждения по стандартам tidyverse и обновляет roxygen2-документацию. CX Codex +1 149установок r-mirai Скилл r-mirai для Claude Code помогает писать R-код для асинхронных и параллельных вычислений через mirai. Включается при настройке воркеров, переносе кода с future или parallel и работе с mirai_map. CX Codex +1 148установок r-cran-extrachecks Скилл r-cran-extrachecks для Claude Code проверяет R-пакет перед отправкой в CRAN на требования, которые пропускает devtools::check(). Запускается при подготовке первой публикации, повторной отправке или разборе замечаний ревьюера. CX Codex +1 144установок shiny-r-optimize Скилл shiny-r-optimize для Claude Code находит причины медленной работы приложений Shiny for R и предлагает правки. Запускается при зависаниях, лишних пересчётах и росте числа пользователей. CX Codex +1 123установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой