Reference

Workflow

Setting up and managing the working environment

Common

scaffold(): Prepare the current Python session for work in the project.
settings(): A settings value by dot-notation key, such as "directories.notebooks".
bootstrap(): Prepare a cloned project so it is ready to work in.

More

capture_output(): Capture everything printed to stdout and stderr inside the block.
config_dir(): The global Framework config folder for Python and fw.
config_sync(): Copy settings and saved logins from the R package's config folder.
configure_global(): Read or update the global settings.
global_settings(): The user's global settings (settings.yml in the config folder), or {}.
load_settings_catalog(): Framework's package defaults, with the user's settings catalog merged over them.
now(): The current local time as an ISO 8601 string, such as 2026-10-30T14:05:09-0400.
project_info(): The project's configured folders and whether each exists yet.
scratch_capture(): Write an object to the scratch folder and return it unchanged.
scratch_clean(): Delete the files in the scratch folder. Subfolders are left alone, as in R.
settings_read(): Read the project settings, with environment sections and split files resolved.
settings_write(): Write project settings.
spec_check(): Problems that would stop project_create(). An empty list means the spec is valid.
spec_resolve(): Merge layers over Python's package defaults into one complete project spec.
status(): Print an overview of the project: settings, git, AI files, and folders.

Data

Reading, writing, and managing data files

Common

data_read(): Read data by catalog name or file path.
data_save(): Save a DataFrame and record its hash.
data_add(): Add an existing file to the data catalog and record its hash.
data_list(): Every catalog entry, with columns name, path, type, locked, and description.

More

data_info(): How to read a data file, given a catalog name or a file path.

Packages

Package management with uv

Common

package_add(): Add a package to the project's dependencies, and install it.
packages_status(): Check that uv.lock is current and the environment matches it.

More

packages_install(): Install the project's dependencies: uv sync, or pip without uv.
packages_list(): The project's dependencies from pyproject.toml, with installed versions.
packages_restore(): Install exactly the versions in uv.lock (uv sync --frozen).
packages_snapshot(): Record the resolved versions in uv.lock (uv lock).
packages_update(): Upgrade locked versions, all of them or the named ones, and install them.

Saving Work

Saving figures, tables, reports, and models

Common

save_table(): Save a table to the tables output folder.
save_figure(): Save a figure to the figures output folder.

More

result_list(): Saved results, newest first.
save_model(): Save a fitted model to the models output folder with pickle (<name>.pkl).
save_notebook(): Render a Quarto notebook or Jupyter notebook and save the result.
save_report(): Copy (or move) a finished report into the reports output folder.

Notebooks & Scripts

Creating notebooks, scripts, and presentations

Common

make_notebook(): Create a notebook from a stub.
make_script(): Create a Python script (.py) in the scripts folder.

More

framework_template_path(): The file your version of a template is saved in (it may not exist yet).
make_presentation(): Create a presentation. The same as make_revealjs().
make_qmd(): Create a Quarto notebook (.qmd) with Python code chunks.
make_revealjs(): Create a Quarto reveal.js presentation.
quarto_generate_all(): Write the project's Quarto configuration, as the R package does. Returns the files written.
quarto_regenerate(): Rewrite the project's Quarto configuration from its settings, backing up the old files.
read_framework_template(): A template's text: yours when you saved one, otherwise Framework's.
reset_framework_template(): Remove your version of a template, so Framework's is used again.
stubs_list(): The available stubs: the project's own, then Framework's.
stubs_path(): Where stubs are read from: the project's stubs/ folder or Framework's.
stubs_publish(): Copy Framework's stubs into the project's stubs/ folder to customize them.
write_framework_template(): Save your version of a template. Returns its path.

Project Management

Creating and managing projects

Common

new(): Create a new Python project with your defaults.
project_create(): Create a Python project from a resolved spec.

More

adopt(): Make an existing folder a Framework project, in place.
project_add_directory(): Create a folder in a project and record it under extra_directories.
project_create_from_layers(): Create a project from a layers file (the format framework.pub sends).
project_list(): Registered projects, with columns id, path, and created.
project_register(): Add a project to the registry in the global settings. Returns its id.
project_root(): The root folder of the Framework project containing start (default: the current folder).
project_unregister(): Remove a project from the registry by id or path. Returns whether it was there.
structure_import(): Save an existing folder's layout as a private structure on Framework Cloud.
tools_available(): Framework's tools for Python projects.

Publishing

Publishing outputs and reports

Common

publish(): Upload a file or folder to the project's storage bucket.
publish_notebook(): Render a Quarto notebook with the quarto command and upload the result.

More

publish_data(): Upload a DataFrame (as CSV, Parquet, or JSON) or a data file.
publish_dir(): Upload the files in a folder. pattern is a regular expression on the paths.
publish_list(): Objects in the bucket (under its prefix): key, size, last_modified, and url.
storage_test(): Whether the bucket exists and the credentials can reach it.

Cloud

Framework Cloud login, settings sync, and the integrity ledger

Common

cloud_login(): Connect this machine to a Framework Cloud server.
cloud_status(): Report the server in use and whether this machine is connected to it.

More

cloud_logout(): Remove this machine's stored token for a server. Returns what was removed.
cloud_settings(): Your settings document from the cloud.
cloud_sync(): Sync your settings document with the cloud. Returns the revision.
data_verify(): Check a catalog file against framework.db and, if connected, the cloud ledger.
ledger_list(): The project's cloud ledger, newest first.
ledger_push(): Send framework.db's file digests to the project's cloud ledger.
skills_sync(): Sync one skill directory. Divergent edits stop without changing either side.

Git

Git hooks and the security audit

Common

git_security_audit(): Check that private data and secrets stay out of git.
git_hooks_install(): Install Framework's pre-commit hook when a hook is enabled in the settings.

More

git_hooks_disable(): Turn off one hook check. The hook is removed when no check is left.
git_hooks_enable(): Turn on one hook check in the settings and (re)install the hook.
git_hooks_list(): The hook checks and whether each is enabled.
git_hooks_uninstall(): Remove Framework's pre-commit hook. A hook Framework did not write is kept.

Caching

Caching computed values for performance

Common

cache_remember(): Return the cached value, or compute it, cache it, and return it.
cache_get(): A cached value, or default when it is missing, expired, or unreadable.

More

cache(): Store a value in the cache and return it.
cache_flush(): Remove every cached value (from R and Python) and every cache record.
cache_forget(): Remove a cached value and its record, whichever language saved it.
cache_list(): Every cache record, with its timestamps and status (active or expired).

Database

Database connections and queries

Common

db_query(): Run a query and return the rows as a DataFrame.
db_execute(): Run a statement, commit it, and return the number of rows affected.

More

connections_list(): Every connection: databases and storage buckets, with the defaults marked.
db_connect(): Open a database connection defined in the settings.
db_drivers_status(): Which database drivers are installed, and the extra that installs each one.
db_list(): Database connections in the settings: name, driver, host, port, and database.
db_transaction(): Commit the block's statements together, or roll all of them back on an error.

AI

AI assistant integration

ai_skills_update(): Refresh clean Framework skills. Preserve local edits and account forks.

Errors and Types

Exceptions, warnings, and the result types functions return

AuditResult: What git_security_audit() found.
BootstrapResult: What bootstrap() did, and what is left for you.
CacheWarning: A cache entry could not be used, so it was treated as a miss.
CapturedOutput: Text printed inside a capture_output() block, stdout and stderr together.
CloudError: A Framework Cloud request failed.
Connection: A DB-API connection from db_connect().
DataChangedWarning: An unlocked data file changed since Framework last recorded its hash.
DataInfo: How to read one data file.
DataNotFoundError: A data catalog name or file path does not resolve to a data file.
FrameworkError: Base class for every error Framework raises.
FrameworkWarning: Base class for warnings Framework issues.
IntegrityError: A locked data file no longer matches the hash recorded in framework.db.
PackagesStatus: Whether the lock file and the environment match pyproject.toml.
ProjectNotFoundError: No Framework project (a folder with settings.yml or config.yml) was found.
ResolvedSpec: A complete project spec and the keys more than one layer set.
SettingsError: A settings file is missing, cannot be parsed, or holds an invalid value.
SpecError: A layer or spec is malformed.
UnsupportedFormatError: A file format Framework cannot read or write from Python.

Getting Started

Features

Project Types

Reference

Workflow

Common

More

Data

Common

More

Packages

Common

More

Saving Work

Common

More

Notebooks & Scripts

Common

More

Project Management

Common

More

Publishing

Common

More

Cloud

Common

More

Git

Common

More

Caching

Common

More

Database

Common

More

AI

Errors and Types