Upref documentation

Upref stores small per-user application configurations through an explicit, typed Python API. Storage, interactive collection, and v1 migration are separate operations, so applications decide exactly when to read, ask, and write.

Start with the overview and quickstart, then use the task-oriented guides below for behavioral details and the API reference for signatures.

Getting started

• Upref
  • Installation
  • Quickstart
  • Configuration values
  • Paths and portable mode
  • Interactive collection
  • Storage guarantees and limits
  • Migrating from v1
  • Security
  • Documentation and examples
  • Development with .venv
  • License
• Configuration model
  • Supported values
  • Detached values and no cache
  • Recursive merge rules
• Examples
  • Basic storage
  • Defaults, update, and delete
  • Terminal collection
  • Migrating from v1

User guide

• Using ConfigStore
  • Loading values
  • Saving the complete mapping
  • Applying selected changes
  • Existence and deletion
  • Atomicity and concurrent access
• Configuration paths
  • Application author and roaming data
  • Custom filenames
  • Explicit directories and portable mode
  • Name validation and confinement
• Interactive collection
  • Defining fields
  • Collecting missing or all values
  • Terminal interface
  • Graphical interface
  • Custom interfaces
• Error handling
  • Exception hierarchy
  • Recovering by operation
  • Programmer errors
• Security and secrets
  • Plain-text storage
  • File permissions
  • Integrity and concurrency
  • Resource limits and untrusted files
  • Application practices
• Migrating from Upref v1
  • Importing one file
  • Migration behavior
  • Deprecated compatibility API

Reference

• API reference
  • Public API summary
  • Configuration storage
  • Configuration types
  • Interactive schema and protocol
  • Built-in interfaces
  • Exceptions
  • Package metadata
• Legacy v1 API reference
  • File and raw-value helpers
  • Descriptor and merge helpers
  • Interactive compatibility helpers
  • Explicit migration function

Project

• Development environment
• MIT License

Site indices

• Index

• Module Index

• Search Page