Skip to main content
Python cells allow you to execute arbitrary Python code in the context of the notebook session. You have access to the full Python standard library and common packages. You can access cell output variables that were set by other cell types. The cells support custom visualization and data processing capabilities. Additionally, you can integrate with external APIs and databases.

​
Variables

You can reference variables set by other python cells on the global scope.

​
Cell Results

All cells - with the exception of Markdown and Python cells, set their output variable ot a CellResult object.

​
Output

Ways to output information from a python cell:
  • Print to stdout/stderr
  • Display objects via IPython.display.display()
  • Return a display object
  • Return a CellResult object
  • Raise an exception

​
Examples

Execute arbitrary Python code for custom logic: 
import pandas as pd
import json
from datetime import datetime, timedelta

# Process error rate data from previous cell
df = pd.DataFrame(splunk_1)
threshold = df['error_rate'].mean() + (2 * df['error_rate'].std())

# Flag services exceeding threshold
problem_services = df[df['error_rate'] > threshold]
print(f"Found {len(problem_services)} services above threshold")

​
Cell Parameters (@param)

NOTE: See Form Cells for the preferred method of adding dynamic user inputs Python cells support inline parameter definitions using the @param comment syntax. Parameters create interactive form inputs that users can modify before running the cell, without editing the code directly. Use @param when you need to parameterize a single cell’s behavior. For inputs that need to be shared across multiple cells, use form cells instead.

​
Basic Syntax

variable = default_value # @param {type:"type_name"}
Parameters must be defined at the top of the cell, after any import statements.

​
Supported Types

​
String

api_url = 'https://api.example.com' # @param {type:"string"}
With additional options: 
service_name = '' # @param {type:"string", label:"Service Name", description:"Enter the service to query", placeholder:"api-gateway"}
Provide a JSON array of choices: 
environment = 'production' # @param ["development", "staging", "production"]
The default value should be one of the choices. If omitted or invalid, the first choice is used.

​
Boolean

verbose = True # @param {type:"boolean"}
show_details = False # @param {type:"boolean", label:"Show Details"}

​
Number

For integers: 
max_results = 100 # @param {type:"integer"}
timeout = 30 # @param {type:"integer", min:1, max:300}
For floating-point numbers: 
threshold = 0.75 # @param {type:"number", min:0.0, max:1.0}

​
Secret

Creates a dropdown of available secrets in the workspace: 
api_key_name = '' # @param {type:"secret", label:"API Key"}

# Use the secret value
api_key = SpinSecrets.get_secret(api_key_name)

​
Connection

Creates a dropdown of available connections: 
# Show all connections
connection_name = '' # @param {type:"connection"}

# Filter by connection scheme(s)
db_connection = '' # @param ["postgres", "mysql"] {type:"connection"}
monitoring_connection = '' # @param ["ddog", "prometheus"] {type:"connection"}

​
Parameter Options

OptionDescription
typeParameter type: string, boolean, integer, number, secret, connection
labelDisplay label for the form input
descriptionHelp text shown below the input
placeholderPlaceholder text for string inputs
minMinimum value for number/integer types
maxMaximum value for number/integer types
requiredWhether the field must have a value (true/false)

​
Dynamic Dropdowns with Selectors

For dropdowns populated dynamically from data, use selectors. Selectors must be created in a prior cell using SpinContext.create_selector(). Cell 1: Create the selector 
# Fetch available options from an API or compute them
regions = ["us-east-1", "us-west-2", "eu-west-1"]

# Create a selector for use in subsequent cells
SpinContext.create_selector("available_regions", regions)

# Selectors can also use dictionaries for value/label pairs
SpinContext.create_selector("region_labels", {
    "us-east-1": "US East (N. Virginia)",
    "us-west-2": "US West (Oregon)",
    "eu-west-1": "EU (Ireland)"
})
Cell 2: Use the selector in a parameter 
region = '' # @param {selector_name:"available_regions"}

# Or with labels
region = '' # @param {selector_name:"region_labels"}
Selectors cannot be created and used in the same cell.

​
Complete Example

# Parameters section - define all inputs at the top
api_url = 'https://api.example.com' # @param {type:"string", label:"API URL"}
api_key_name = '' # @param {type:"secret", label:"API Key"}
environment = 'production' # @param ["development", "staging", "production"]
max_results = 100 # @param {type:"integer", min:1, max:1000}
verbose = False # @param {type:"boolean"}

# Get the actual secret value
api_key = SpinSecrets.get_secret(api_key_name)

# Use the parameters in your code
import requests

headers = {"Authorization": f"Bearer {api_key}"}
params = {"env": environment, "limit": max_results}

response = requests.get(f"{api_url}/data", headers=headers, params=params)
data = response.json()

if verbose:
    SpinLog.info(f"Retrieved {len(data)} records from {environment}")

CellResult.set_py_result(data)

​
Packages

The following python packages are pre-installed in the spin runtime container.
PackageVersionPurpose
datadog-api-client^2.29.0Datadog integration
pyyaml^6.0.2YAML parsing
splunk-sdk^2.1.0Splunk integration
fastapi^0.100.0API framework
httpx^0.25.0HTTP client
uvicorn^0.25.0ASGI server
websockets^11.0.0WebSocket support
jupyter-client^8.0.0Jupyter kernel communication
notebook^7.0.0Jupyter notebook
cryptography^42.0.0Crypto operations
pyjwt^2.10.1JWT handling
openai^1.91.0OpenAI API client
sqlalchemy^2.0.0SQL toolkit/ORM
pandas^2.2.0Data analysis
psycopg2-binary^2.9.0PostgreSQL driver
pymysql^1.1.0MySQL driver
clickhouse-connect^0.9.0ClickHouse driver
apscheduler^3.10.4Task scheduling
boto3^1.28.0AWS SDK
google-cloud-storage^3.7.0GCS SDK

​
Installing additional packages and utility

Additional packages can be installed by using a shell cell in any notebook to run pip install. E.g. 
pip install my_new_package
Packages installed this way will persist across notebooks and sessions but may need to be reinstalled if the runtime is restarted or a new version is pulled.

​
Custom Runtime Images

To create a custom image with a python package (or additional other utility) pre-installed, use a custom Dockerfile e.g. 
FROM ghcr.io/siftd/spin-runtime:latest-prod

# pip install directly
RUN pip install my_new_package another_new_package

# Or use a requirements.txt file (must copy to the container first)
COPY requirements.txt
RUN pip install requirements.txt

# install kcat package using apt.  
apt install -y kcat