Scripts

Quarto supports rendering script files (e.g., .py, or .R) that are specially formatted. Posit Connect can render these scripts using Quarto.

Note

Script rendering was first introduced in Quarto 1.4.

Scripts can be used for many different data processing purposes, including any of the following:

A standalone script can be deployed to Connect. Scripts can also be published to Connect within a Quarto project alongside other Markdown content.

Output from scripts is retained and served when you visit the hosted content.

You can schedule the execution of scripts in Connect. Additionally, script files produce custom email when they produce an email Markdown block.

Simple example

These Python and R 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 Python and R 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 Python and R 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:

quarto render script.py

Render a project:

quarto render

Render a single file:

quarto render script.R

Render a project:

quarto render

The 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:

quarto preview script.py

Preview a project:

quarto preview

Preview a single file:

quarto preview script.R

Preview a project:

quarto preview

Publishing

Python scripts are deployed from the command line using the rsconnect-python Python package.

Before getting started, make sure that you have installed the rsconnect-python package and linked your Connect account.

Note

Use rsconnect-python 1.23.0 or higher when publishing scripts.

You can deploy a script by itself:

rsconnect deploy quarto script.py

You can also deploy a script along with supporting files:

rsconnect deploy quarto script.py helper.py data.csv

When your script is part of a Quarto project having a _quarto.yml file, you can deploy the project directory:

rsconnect deploy quarto .

The rsconnect deploy considers all of the files in the current directory when publishing.

For additional details about the rsconnect deploy command and its arguments, see the rsconnect-python documentation.

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.

Note

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.