Scripts
Posit Connect supports rendering script files (e.g., .py, or .R). Scripts are rendered using Quarto, an open-source scientific and technical publishing system built on Pandoc. Script files must be specially formatted for Quarto to recognize and render them.
Script rendering requires at least Quarto 1.4.
Scripts can be used for many different data processing purposes, including any of the following:
- Extract (read) from files / databases
- Transform / tidy (clean) data
- Load (write) into files / databases
A standalone script can be deployed to Connect. Scripts can also be published to Connect within a Quarto project alongside other Markdown content.
Output produced by scripts is presented by Connect when you visit the content. The output may be simple text messages produced by the script, or may include formatted text, images, and interactive elements.
You can schedule the execution of scripts in Connect. Additionally, script files produce custom email when they produce an email Markdown block.
Prerequisites
Install these prerequisites into your development environment before running the examples on this page.
uv to manage the Python environment.
A uv project with the Quarto Python requirements. In the directory for your scripts, create a project and add Jupyter:
Terminal
uv init --bare --python 3.12 --pin-python uv add jupyterReplace
3.12with the Python version that your scripts use. See setting up your project for details.Packages used by the examples.
Terminal
uv add pandasInstall the Posit CLI for deployment.
Quarto R requirements
install.packages("rmarkdown")Packages used for deployment.
# rsconnect 1.2.2 or higher is required. install.packages("rsconnect")
In order to deploy scripts, your Connect server must be configured with compatible versions of Quarto, Python, and R.
Simple example
These examples show some very basic script files that can be rendered by Quarto. They both construct random data and write a CSV file.
# %% [markdown]
# ---
# title: "Python script file"
# ---
# %%
import datetime
import pandas as pd
import random
# Randomly generate data that acts as 30-day trailing unit sales.
today = datetime.date.today()
data = pd.DataFrame({
'Date': pd.date_range(
today - datetime.timedelta(days=30),
today - datetime.timedelta(days=1),
),
'Sales': [random.randint(75, 100) for _ in range(1, 31)],
})
# Write a CSV for downstream use.
data.to_csv("sales.csv", index=False)
# %% [markdown]
# Download [CSV](sales.csv)#' ---
#' title: "R script file"
#' ---
# Randomly generate data that acts as 30-day trailing unit sales.
today <- Sys.Date()
data <- data.frame(
Date = today - 1:30,
Sales = sample(75:100, 30, replace = TRUE)
)
# Write a CSV for downstream use.
write.csv(data, "sales.csv", row.names = FALSE)
#' Download [CSV](sales.csv)When adapting existing scripts, you must add an initial front-matter comment:
# %% [markdown]
# ---
# title: "Data processing script"
# ---#' ---
#' title: "Data processing script"
#' ---See the Quarto documentation for additional syntax and examples.
Email example
These examples show how to produce custom email from a script file.
# %% [markdown]
# ---
# title: "Python script custom email"
# format: email
# ---
# %%
import random
choices = [ "red", "orange", "yellow", "green", "blue", "indigo", "violet" ]
choice = random.choice(choices)
choice
# %% [markdown]
# ::: {.email}
# ::: {.subject}
# Custom email from a Python script
# :::
# %%
#| echo: false
#| output: asis
print(f"Color of the day: {choice}")
# %% [markdown]
# :::#' ---
#' title: "R script custom email"
#' format: email
#' ---
choices <- c("red", "orange", "yellow", "green", "blue", "indigo", "violet")
choice <- sample(choices, 1)
choice
#' ::: {.email}
#' ::: {.subject}
# Custom email from an R script
#' :::
#| echo: false
#| output: asis
cat("Color of the day: ", choice, "\n")
#' :::Render and preview
You can render and preview notebook scripts from the command line, just as you would other types of Quarto content.
Depending on your configuration, you can preview and render an entire project or a specific file.
The Quarto render command runs the targeted content and writes the results to disk.
Render a single file:
Terminal
uv run quarto render script.pyRender a project:
Terminal
uv run quarto renderRender a single file:
Terminal
quarto render script.RRender a project:
Terminal
quarto renderThe Quarto preview command renders the targeted content and opens a browser to visit that content. Your content is refreshed after an edit.
Preview a single file:
Terminal
uv run quarto preview script.pyPreview a project:
Terminal
uv run quarto previewPreview a single file:
Terminal
quarto preview script.RPreview a project:
Terminal
quarto previewPublishing
Deploy Python scripts from the command line using the Posit CLI.
Before publishing, install the Posit CLI and sign in to Connect.
You can deploy a script by itself:
Terminal
posit connect deploy quarto script.pyYou can also deploy a script along with supporting files:
Terminal
posit connect deploy quarto script.py helper.py data.csvWhen your script is part of a Quarto project having a _quarto.yml file, you can deploy the project directory:
Terminal
posit connect deploy quarto .Each of these commands reads your package dependencies from a requirements.txt file in the same directory as the script or project. If the file does not exist, the command stops with an error. To create the file, export your project’s locked dependencies:
Terminal
uv export --no-dev --no-emit-project --no-hashes -o requirements.txtSee package dependencies for other options.
When you deploy a script file, posit connect deploy uploads only that file, any additional files you list, requirements.txt, and the generated manifest. It doesn’t include other files in the directory, so list every helper or data file that your script needs. When you deploy a directory, posit connect deploy considers all of the files in that directory.
For command arguments, see the posit connect deploy quarto reference.
R scripts are deployed from RStudio and the R console with the rsconnect R package. Unlike some other content types, push-button publishing is not available for R scripts.
Use rsconnect 1.2.2 or higher when publishing scripts.
Before getting started, make sure that you have linked your Connect account from your R session. This only needs to be done once.
From the project directory containing your R script, use rsconnect::deployApp() to publish your script.
rsconnect::deployApp()The call to rsconnect::deployApp() considers all of the files in the current directory when determining how to deploy them. If you are deploying a standalone R script, you probably want a directory containing only the script file or the script file with a _quarto.yml file. If your R script is contained in a directory with many other files, call deployApp() with the appFiles argument in order to control exactly which files to include.
rsconnect::deployApp(appFiles = c("_quarto.yml", "script.R", "helper.R"))For additional details about appFiles and other arguments, see the rsconnect::deployApp() documentation.