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.

Note

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.

Python

1. Quarto 1.4 or newer.

2. Quarto Python requirements

   python3 -m pip install jupyter

3. Packages used by the examples.

   python3 -m pip install pandas

4. Packages used for deployment.

   # rsconnect-python 1.23.0 or higher is required.
   python3 -m pip install rsconnect-python

R

1. Quarto 1.4 or newer.

2. Quarto R requirements

   install.packages("rmarkdown")

3. 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 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.

Python

# %% [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)

R

#' ---
#' 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:

Python

# %% [markdown]
# ---
# title: "Data processing script"
# ---

R

#' ---
#' 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.

Python

# %% [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]
# :::

R

#' ---
#' 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.

Python

Render a single file:

quarto render script.py

Render a project:

quarto render

R

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.

Python

Preview a single file:

quarto preview script.py

Preview a project:

quarto preview

R

Preview a single file:

quarto preview script.R

Preview a project:

quarto preview

Publishing

Python

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

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.