Persistence: Save, Load, Push, Pull

All EDSL objects (including Survey and SurveyList) inherit persistence methods from the Base class.

Local File Persistence (save/load)

Saving to Local Files

python

from edsl import Survey

survey = Survey([q1, q2, q3])

# Save survey (compressed by default)
survey.save("my_survey")  # Creates my_survey.json.gz

# Save uncompressed
survey.save("my_survey", compress=False)  # Creates my_survey.json

# Filename extensions are handled automatically
survey.save("my_survey.json.gz")  # Works the same
survey.save("my_survey.json")     # Works the same

Loading from Local Files

python

from edsl import Survey

# Load a survey
survey = Survey.load("my_survey")  # Auto-detects .json.gz or .json

# Explicit extensions work too
survey = Survey.load("my_survey.json.gz")
survey = Survey.load("my_survey.json")

File Format Details

•Compressed (default): .json.gz - gzip-compressed JSON, smaller file size
•Uncompressed: .json - plain JSON, human-readable
•Both formats store the complete survey state including questions, rules, memory, etc.
•The load() method auto-detects the format based on file extension

Cloud Persistence (push/pull)

Surveys can be stored on the Expected Parrot cloud platform for sharing and collaboration.

Pushing to the Cloud

python

from edsl import Survey

survey = Survey([q1, q2, q3])

# Basic push (unlisted by default)
response = survey.push()
print(response)  # Contains UUID and URL

# Push with metadata
response = survey.push(
    description="Customer satisfaction survey Q4 2024",
    alias="customer-satisfaction",    # Human-readable identifier
    visibility="private"              # "private", "unlisted", or "public"
)

# Update existing object (when alias already exists)
response = survey.push(
    alias="customer-satisfaction",
    force=True  # Patches existing object instead of creating new
)

Pulling from the Cloud

python

from edsl import Survey

# Pull by UUID
survey = Survey.pull("123e4567-e89b-12d3-a456-426614174000")

# Pull by full URL
survey = Survey.pull("https://expectedparrot.com/content/123e4567...")

# Pull by alias URL
survey = Survey.pull("https://expectedparrot.com/content/username/customer-satisfaction")

# Pull by shorthand alias (username/alias)
survey = Survey.pull("username/customer-satisfaction")

Listing Cloud Objects

python

from edsl import Survey

# List your Surveys on the cloud
my_surveys = Survey.list()

# Filter by visibility
public_surveys = Survey.list(visibility="public")
private_surveys = Survey.list(visibility="private")

# Search by description
matching = Survey.list(search_query="customer satisfaction")

# Pagination
page_2 = Survey.list(page=2, page_size=20)

# Sort order (default: newest first)
oldest_first = Survey.list(sort_ascending=True)

Managing Cloud Objects

python

from edsl import Survey

# Update an existing object's metadata
Survey.patch(
    "123e4567-e89b-12d3-a456-426614174000",
    description="Updated description",
    visibility="public"
)

# Update with new value (instance method)
survey = Survey([q1, q2, q3, q4])  # Updated survey
survey.patch(
    "123e4567-e89b-12d3-a456-426614174000",
    description="Added question 4"
)

# Delete from cloud
Survey.delete("123e4567-e89b-12d3-a456-426614174000")

Visibility Levels

Level	Description
`"private"`	Only you can access
`"unlisted"`	Anyone with the URL/UUID can access (default)
`"public"`	Discoverable and accessible by everyone

Git-Based Versioning

Survey supports git-like version control for tracking changes over time.

python

from edsl import Survey

# Push to git-based storage
survey.git_push("my-survey")

# Clone from git-based storage
survey = Survey.git_clone("username/my-survey")

Serialization to Dict/JSON/YAML

python

# To/from dictionary
d = survey.to_dict()
survey = Survey.from_dict(d)

# To JSON string
json_str = survey.to_json()

# To/from YAML
yaml_str = survey.to_yaml()
survey = Survey.from_yaml(yaml_str)

# Save YAML to file
survey.to_yaml(filename="survey.yaml")
survey = Survey.from_yaml(filename="survey.yaml")

Export to Other Formats

python

# Export to Qualtrics-compatible format (if supported)
# survey.to_qsf("survey.qsf")

# Export to pandas DataFrame (question metadata)
# df = survey.to_pandas()

SurveyList Persistence

python

from edsl import SurveyList

# Create a collection of surveys
surveys = SurveyList([survey1, survey2, survey3])

# Save/load works the same way
surveys.save("my_surveys")
surveys = SurveyList.load("my_surveys")

# Cloud operations
surveys.push(description="Survey collection", alias="my-survey-collection")
surveys = SurveyList.pull("uuid-or-alias")

Quick Reference

Task	Single Survey	SurveyList
Save locally	`survey.save("file")`	`surveys.save("file")`
Load locally	`Survey.load("file")`	`SurveyList.load("file")`
Push to cloud	`survey.push(alias="...")`	`surveys.push(alias="...")`
Pull from cloud	`Survey.pull("uuid")`	`SurveyList.pull("uuid")`
List on cloud	`Survey.list()`	`SurveyList.list()`
Delete from cloud	`Survey.delete("uuid")`	`SurveyList.delete("uuid")`
To dict	`survey.to_dict()`	`surveys.to_dict()`
From dict	`Survey.from_dict(d)`	`SurveyList.from_dict(d)`