upref 2.1.0__tar.gz → 2.2.0__tar.gz

{upref-2.1.0 → upref-2.2.0}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 2.2.0 - 2026-09-26
+
+### Added
+
+- Ten runnable user-preference scenarios: first-run setup, Apply/Cancel, resets,
+  recent documents, window geometry, account settings, CLI session overrides,
+  portable JSON import/export, backup/restore, and legacy migration preview.
+  The catalog now contains 26 examples, with a dedicated walkthrough guide.
+- Explicit `source_format="auto" | "raw" | "descriptors"` selection and
+  `dry_run=True` previews for legacy migration, retaining the default heuristic
+  and target preflight checks.
+- Hypothesis properties for persistence, copying, merging, and failed writes.
+- Native wxPython integration scenarios with process timeouts and a dedicated
+  Windows CI job; minimum runtime dependency testing on Python 3.10.
+- Functional installed-wheel and resource checks in CI and release automation.
+- A release-based deprecation schedule: v1 wrappers remain through 2.x and are
+  scheduled for removal in 3.0. Explicit migration remains supported.
+
+### Fixed
+
+- Preserve Unicode NEL (U+0085) in YAML keys and values instead of folding it
+  into a space; ordinary Unicode remains readable.
+- Reject non-scalar YAML keys carrying scalar tags with `ConfigFormatError`
+  and a source location instead of leaking a `TypeError`.
+- Reject null characters in configuration directories during construction.
+- Normalize string subclass keys to plain strings, preserving their underlying
+  text so string-backed enum keys can be saved. Scalar enum values still need
+  explicit conversion; normalized key collisions are rejected.
+- Measure branch coverage as well as statement coverage, retaining the 100%
+  gate and covering application reuse and pre-write failures.
+- Exercise POSIX and Windows permission branches on every platform so the
+  coverage gate behaves consistently on Linux, macOS, and Windows.
+
+### Compatibility
+
+- Python 3.10 and later remain supported, with no new runtime dependency.
+- Existing migration calls retain their behavior; format selection and previews
+  are optional. Deprecated v1 wrappers remain available throughout 2.x.
+- Malformed YAML keys and invalid configuration directories now consistently
+  raise the documented configuration exceptions. Duplicate normalized keys are
+  rejected instead of silently replacing an existing value.
+
 ## 2.1.0
 
 ### Added

{upref-2.1.0 → upref-2.2.0}/MANIFEST.in

@@ -2,5 +2,6 @@ include pytest.ini make.bat .gitattributes
 include CHANGELOG.md
 recursive-include examples *.py *.md
 recursive-include scripts *.py *.ps1
+recursive-include tests *.py
 recursive-include docs *.rst *.md *.py *.css *.png
 prune docs/_build

{upref-2.1.0 → upref-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: upref
-Version: 2.1.0
+Version: 2.2.0
 Summary: Small, explicit, and safe per-user configuration storage
 Author: Florent Tournois
 License-Expression: MIT
@@ -25,6 +25,7 @@ Requires-Dist: PyYAML>=6.0
 Provides-Extra: gui
 Requires-Dist: wxPython>=4.2; extra == "gui"
 Provides-Extra: test
+Requires-Dist: hypothesis>=6.100; extra == "test"
 Requires-Dist: mypy>=2; extra == "test"
 Requires-Dist: pytest>=8; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
@@ -36,6 +37,7 @@ Requires-Dist: sphinx>=7; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
 Requires-Dist: mypy>=2; extra == "dev"
 Requires-Dist: myst-parser>=2; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
@@ -245,10 +247,18 @@ store = ConfigStore("my-application")
 config = store.import_legacy("my_personnal_data")
 ```
 
+For ambiguous files, choose ``source_format="raw"`` to retain the entire
+mapping, or ``source_format="descriptors"`` to extract v1 values explicitly.
+Add ``dry_run=True`` to inspect the conversion without writing. Previewing
+still performs source and target preflight checks. The default ``"auto"``
+format retains the historical heuristic.
+
 The source file is left untouched, and using it as the v2 target is rejected.
 Migration checks for an existing v2 file unless `overwrite=True` is passed;
 because this preflight check is not locked, applications with concurrent
 writers must coordinate the migration externally.
+Deprecated v1 wrappers remain available throughout 2.x and are scheduled for
+removal in 3.0; explicit file migration remains supported.
 
 ## Security
 
@@ -263,13 +273,18 @@ reference in Upref.
 
 The complete user guide and API reference are available on
 [Read the Docs](https://upref.readthedocs.io/). The
-[example catalog](docs/examples.rst) lists 16 runnable programs by difficulty,
+[example catalog](docs/examples.rst) lists 26 runnable programs by difficulty,
 input method, and file effects. Start with these:
 
 | Level | Example | What it demonstrates |
 | --- | --- | --- |
 | Simple | `portable_store.py` | Defaults, save/load, and updates in a temporary directory |
 | Simple | `boolean_collection.py` | Boolean parsing, optional input, and cancellation |
+| Simple | `first_run_preferences.py` | Initial user setup and reuse on the next startup |
+| Intermediate | `apply_preferences.py` | Edit a draft, then confirm or discard changes |
+| Intermediate | `reset_preferences.py` | Restore one preference, a section, or all defaults |
+| Intermediate | `session_overrides.py` | CLI overrides with explicit `--remember` persistence |
+| Advanced | `import_export_preferences.py` | Validated preference transfer with local history retained |
 | Intermediate | `edit_settings.py` | Enter to keep values and editable JSON lists |
 | Intermediate | `gui_collection.py` | GUI ownership, formatted prefill, and cancellation |
 | Intermediate | `handle_errors.py` | Reporting malformed YAML while retaining the file |
@@ -288,6 +303,10 @@ python examples/portable_store.py
 python examples/custom_interface.py
 ```
 
+The [user preference walkthroughs](docs/user_preferences.rst) also cover recent
+documents, window geometry, multiple accounts, backup/restore, and previewing
+legacy migration. Every scenario in that guide uses temporary files.
+
 See also the [troubleshooting guide](docs/troubleshooting.rst) and the
 [code review and compatibility notes](docs/review.rst).
 

{upref-2.1.0 → upref-2.2.0}/README.md

@@ -195,10 +195,18 @@ store = ConfigStore("my-application")
 config = store.import_legacy("my_personnal_data")
 ```
 
+For ambiguous files, choose ``source_format="raw"`` to retain the entire
+mapping, or ``source_format="descriptors"`` to extract v1 values explicitly.
+Add ``dry_run=True`` to inspect the conversion without writing. Previewing
+still performs source and target preflight checks. The default ``"auto"``
+format retains the historical heuristic.
+
 The source file is left untouched, and using it as the v2 target is rejected.
 Migration checks for an existing v2 file unless `overwrite=True` is passed;
 because this preflight check is not locked, applications with concurrent
 writers must coordinate the migration externally.
+Deprecated v1 wrappers remain available throughout 2.x and are scheduled for
+removal in 3.0; explicit file migration remains supported.
 
 ## Security
 
@@ -213,13 +221,18 @@ reference in Upref.
 
 The complete user guide and API reference are available on
 [Read the Docs](https://upref.readthedocs.io/). The
-[example catalog](docs/examples.rst) lists 16 runnable programs by difficulty,
+[example catalog](docs/examples.rst) lists 26 runnable programs by difficulty,
 input method, and file effects. Start with these:
 
 | Level | Example | What it demonstrates |
 | --- | --- | --- |
 | Simple | `portable_store.py` | Defaults, save/load, and updates in a temporary directory |
 | Simple | `boolean_collection.py` | Boolean parsing, optional input, and cancellation |
+| Simple | `first_run_preferences.py` | Initial user setup and reuse on the next startup |
+| Intermediate | `apply_preferences.py` | Edit a draft, then confirm or discard changes |
+| Intermediate | `reset_preferences.py` | Restore one preference, a section, or all defaults |
+| Intermediate | `session_overrides.py` | CLI overrides with explicit `--remember` persistence |
+| Advanced | `import_export_preferences.py` | Validated preference transfer with local history retained |
 | Intermediate | `edit_settings.py` | Enter to keep values and editable JSON lists |
 | Intermediate | `gui_collection.py` | GUI ownership, formatted prefill, and cancellation |
 | Intermediate | `handle_errors.py` | Reporting malformed YAML while retaining the file |
@@ -238,6 +251,10 @@ python examples/portable_store.py
 python examples/custom_interface.py
 ```
 
+The [user preference walkthroughs](docs/user_preferences.rst) also cover recent
+documents, window geometry, multiple accounts, backup/restore, and previewing
+legacy migration. Every scenario in that guide uses temporary files.
+
 See also the [troubleshooting guide](docs/troubleshooting.rst) and the
 [code review and compatibility notes](docs/review.rst).
 

{upref-2.1.0 → upref-2.2.0}/docs/concepts.rst

@@ -45,9 +45,13 @@ of the following:
 Empty strings, empty containers, ``False``, and ``0`` are valid values. An
 empty document or explicit YAML ``null`` at the root represents an empty
 mapping. A list or non-null scalar at the document root is invalid. Mapping
-keys at every level must be strings.
+keys at every level must be strings. Keys derived from ``str``, including
+string-backed enum members, are normalized to ordinary strings using their
+underlying text. A customized ``__str__`` display does not rename the key.
+If distinct custom keys normalize to the same text, validation rejects the
+collision instead of discarding a value.
 
-Objects such as ``pathlib.Path``, ``datetime``, tuples, sets, enum
+Values such as ``pathlib.Path``, ``datetime``, tuples, sets, enum
 members, and application classes are not converted implicitly. Convert them
 to a supported representation before calling
 :meth:`~upref.ConfigStore.save`.

{upref-2.1.0 → upref-2.2.0}/docs/development.rst

@@ -82,19 +82,46 @@ Equivalent tools can be run directly through the environment interpreter:
    .\.venv\Scripts\python.exe -m mypy upref examples
    .\.venv\Scripts\python.exe -m sphinx -E -a -W --keep-going -b html docs docs\_build\html
 
-Continuous integration also measures statement coverage and requires 100
-percent. Reproduce that gate locally with:
+Continuous integration measures statement and branch coverage and requires
+100 percent. Reproduce that gate locally with:
 
 .. code-block:: console
 
    .\.venv\Scripts\python.exe -m pytest --cov=upref --cov-report=term-missing
 
-Behavioral checks matter in addition to statement coverage. ``test_examples.py``
+Behavioral checks matter in addition to coverage. ``test_properties.py`` uses
+Hypothesis to generate nested configurations and verify YAML round trips,
+independence of mutable containers, merge identities, and preservation of the
+original file after a failed replacement. NaN is excluded from equality-based
+properties because it does not compare equal to itself.
+
+``test_examples.py``
 runs storage and advanced recipes in isolated directories, supplies deterministic
 terminal answers, and verifies cancellation without saving. Tests for GUI
 arguments and lifecycle use a wxPython substitute and do not require a display.
-After changing GUI presentation, also run ``examples/gui_collection.py`` in a
-desktop session with the GUI extra installed to check actual rendering.
+Native GUI integration tests run in a dedicated Windows CI job. Each scenario
+uses a separate process with a 40-second timeout and drives real modal dialogs
+through wx's event loop. They check app ownership, repeated dialogs, formatted
+prefill, cancellation, password controls, and cleanup after an injected error.
+They are skipped in the ordinary suite. Run them in a desktop session with:
+
+.. code-block:: powershell
+
+   .\.venv\Scripts\python.exe -m pip install -e '.[test,gui]'
+   $env:UPREF_RUN_GUI_TESTS = '1'
+   .\.venv\Scripts\python.exe -m pytest tests/integration -q --no-cov
+   Remove-Item Env:UPREF_RUN_GUI_TESTS
+
+The dedicated run disables coverage because the complete coverage gate belongs
+to the ordinary unit suite. Missing wxPython is an error when native tests are
+explicitly enabled. Visual layout can additionally be inspected with
+``examples/gui_collection.py``.
+
+CI also runs the ordinary suite on Python 3.10 with ``platformdirs==4.0.0`` and
+``PyYAML==6.0`` to check the advertised minimum runtime dependencies. The wheel
+job and release workflow invoke ``scripts/check_installed_package.py`` using
+Python's isolated mode in a clean environment: it checks packaged resources
+and the save/load/update/delete cycle without importing the checkout.
 
 Documentation workflow
 ----------------------

{upref-2.1.0 → upref-2.2.0}/docs/examples.rst

@@ -3,11 +3,12 @@
 Examples
 ========
 
-The 16 programs in ``examples`` are complete and runnable from a checkout with
-the project installed in ``.venv``. The nine recipes listed first use memory
-or automatically cleaned temporary directories. The seven persistent examples
-below use distinct per-user configuration locations; migration reads an
-existing historical file and creates a separate v2 file.
+The 26 programs in ``examples`` are complete and runnable from a checkout with
+the project installed in ``.venv``. Ten user-preference scenarios and nine
+fundamental recipes use memory or automatically cleaned temporary directories.
+The seven persistent examples below use distinct per-user configuration
+locations; migration reads an existing historical file and creates a separate
+v2 file.
 
 Run an example on Windows with:
 
@@ -15,6 +16,39 @@ Run an example on Windows with:
 
    .\.venv\Scripts\python.exe examples\basic_store.py
 
+User preference scenarios
+--------------------------
+
+Start with :doc:`user_preferences` for everyday application behavior. All ten
+scenarios use temporary files, and only the first two require terminal input.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Script
+     - User scenario
+   * - ``first_run_preferences.py``
+     - Initial setup and reuse on the next startup.
+   * - ``apply_preferences.py``
+     - Edit a draft, then confirm, discard, or cancel.
+   * - ``reset_preferences.py``
+     - Remove one override, a section, or the whole configuration.
+   * - ``recent_files.py``
+     - Keep a bounded history of recently opened documents.
+   * - ``window_preferences.py``
+     - Restore visible window geometry after changing displays.
+   * - ``account_preferences.py``
+     - Keep separate preferences for accounts within one OS user.
+   * - ``session_overrides.py``
+     - Override preferences through CLI options with opt-in persistence.
+   * - ``import_export_preferences.py``
+     - Transfer validated portable preferences without local history.
+   * - ``backup_restore.py``
+     - Restore a previous preference snapshot.
+   * - ``migration_preview.py``
+     - Preview legacy conversion and preserve ambiguous raw data.
+
 Progressive recipes
 -------------------
 

{upref-2.1.0 → upref-2.2.0}/docs/index.rst

@@ -17,6 +17,7 @@ task-oriented guides below for behavioral details and the :doc:`API reference
    readme_link
    concepts
    examples
+   user_preferences
    recipes
 
 .. toctree::

{upref-2.1.0 → upref-2.2.0}/docs/migration.rst

@@ -60,15 +60,45 @@ Migration behavior
 * recognized descriptor mappings are converted to raw values and metadata
   entries and descriptors without a ``value`` member are omitted;
 * the destination uses the same validation and atomic save as every v2 store;
-* the returned mapping is the mapping written to the destination.
+* the returned mapping is the mapping written to the destination, or the
+  proposed conversion when ``dry_run=True``.
 
 Descriptor detection is necessarily structural because v1 files carry no
 format version. Upref treats a document as descriptors when every
 non-metadata top-level value is a mapping containing at least one of
 ``label``, ``description``, ``type``, or ``value``, and at least one field has
 a ``value`` member. A raw configuration with that same shape is ambiguous and
-may be converted. For such data, load and transform it explicitly before
-calling :meth:`~upref.ConfigStore.save`.
+may be converted. Use ``source_format="raw"`` to preserve every key of such
+data. Use ``source_format="descriptors"`` to force extraction of ``value``
+entries, dropping metadata and descriptors without a value. The default,
+``source_format="auto"``, retains the historical detection behavior.
+
+For example, ``{"timeout": {"value": 30, "unit": "seconds"}}`` becomes
+``{"timeout": 30}`` in auto or descriptor mode. Raw mode preserves the full
+mapping, including ``unit``.
+
+Previewing a conversion
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Inspect the conversion without writing or creating the destination directory:
+
+.. code-block:: python
+
+   preview = store.import_legacy(
+       "my_personnal_data", source_format="raw", dry_run=True
+   )
+   # Inspect or validate preview before choosing to perform the import.
+   migrated = store.import_legacy("my_personnal_data", source_format="raw")
+
+A dry run still checks that the source exists, source and target differ, and
+the target does not already exist unless ``overwrite=True``. It does not test
+write permissions or serialization at the destination. Previewing an existing
+target with ``overwrite=True, dry_run=True`` leaves that target unchanged.
+The returned tree is detached. A later import reads the source again; a preview
+neither reserves the target nor freezes the source against other writers.
+
+Overwriting a target
+~~~~~~~~~~~~~~~~~~~~~
 
 Use ``overwrite=True`` only after deciding that the legacy file is the source
 of truth:
@@ -117,3 +147,16 @@ replacements:
 The compatibility layer preserves v1 locations and descriptor shape; it is
 not the recommended way to create a new v2 file. See :doc:`legacy_api` for its
 complete reference.
+
+Removal schedule
+~~~~~~~~~~~~~~~~
+
+The compatibility wrappers remain supported throughout all 2.x releases.
+Their removal is scheduled for 3.0, and their warnings name that boundary.
+There is no calendar release date for 3.0. Migrate callers and run application
+tests with deprecation warnings enabled before adopting that major version.
+
+This schedule covers the deprecated functions listed above, both at package
+level and in ``upref.legacy``. Explicit file migration through
+``ConfigStore.import_legacy`` is retained; removing the wrappers will not
+require users to abandon old files before they can upgrade.

{upref-2.1.0 → upref-2.2.0}/docs/recipes.rst

@@ -6,6 +6,10 @@ them from an installed checkout with ``python examples/<name>.py``. All files
 created by the recipes below use automatically cleaned temporary directories;
 the interactive collection examples otherwise work entirely in memory.
 
+For first-run setup, Apply/Cancel, resets, recent documents, window geometry,
+account preferences, session overrides, and preference transfer, see the ten
+additional walkthroughs in :doc:`user_preferences`.
+
 A first store without persistent files
 --------------------------------------
 

{upref-2.1.0 → upref-2.2.0}/docs/releasing.rst

@@ -38,7 +38,7 @@ Preparing a release
 -------------------
 
 Release tags use a ``v`` prefix while Python package metadata does not. For
-example, package version ``2.1.0`` is released with tag ``v2.1.0``.
+example, package version ``2.2.0`` is released with tag ``v2.2.0``.
 
 #. Update ``project.version`` in ``pyproject.toml`` and the source-tree fallback
    ``upref.__version__`` in ``upref/__init__.py`` to the same PEP 440 version.
@@ -67,8 +67,8 @@ example, package version ``2.1.0`` is released with tag ``v2.1.0``.
 
    .. code-block:: console
 
-      git tag -a v2.1.0 -m "Release v2.1.0"
-      git push origin v2.1.0
+      git tag -a v2.2.0 -m "Release v2.2.0"
+      git push origin v2.2.0
 
 The release workflow rejects a tag that does not match ``project.version``,
 does not identify the checked-out commit, or does not belong to ``master``.

{upref-2.1.0 → upref-2.2.0}/docs/review.rst

@@ -108,3 +108,28 @@ heuristic can be ambiguous for raw mappings that resemble descriptors. These
 constraints are described in :doc:`security`, :doc:`storage`, and
 :doc:`migration`; addressing them requires separate API and compatibility
 decisions.
+
+Follow-up hardening
+-------------------
+
+The subsequent implementation adds explicit migration format selection and
+dry-run previews while preserving the default heuristic. Invalid scalar-tagged
+YAML keys now report format errors, null characters in directories are rejected
+at construction, and string subclass keys are normalized to ordinary strings.
+
+Generated round-trip tests found that PyYAML folds Unicode NEL (U+0085) into a
+space when emitted literally. Upref's safe dumper now escapes that character
+in keys and values while retaining readable ordinary Unicode. Temporary-file
+cleanup is registered when the file is created and runs after the stream closes,
+including on write, flush, permission, and replacement failures.
+
+The local Windows/Python 3.14 suite passes 267 tests with 100% statement and
+branch coverage. Three platform-dependent checks and the two opt-in native GUI
+scenarios are skipped by the ordinary command. The two native scenarios were
+also run separately with wxPython 4.3.1 and passed, exercising both owned and
+borrowed applications with real dialogs.
+
+CI now includes native GUI and minimum-runtime-dependency jobs. CI and release
+automation check installed-wheel resources and persistence in isolated mode.
+The 2.x/3.0 wrapper removal schedule is documented in :doc:`migration`;
+criteria for adding locking or resource budgets are in :doc:`security`.

{upref-2.1.0 → upref-2.2.0}/docs/security.rst

@@ -88,3 +88,19 @@ Applications using Upref should also:
 * treat configuration imported from another machine as untrusted input;
 * keep backups and crash reports from collecting secrets accidentally;
 * add cross-process locking when lost updates are unacceptable.
+
+Criteria for expanding the storage contract
+-------------------------------------------
+
+Upref's current scope remains small, local configuration files. If an
+application allows several processes to write the same file and cannot accept
+lost updates, coordinate the complete read/merge/write operation with an
+external lock. A future built-in transaction API would need portable locking,
+timeouts, failure recovery, and multiprocess tests before becoming a guarantee.
+
+If configurations will be accepted from external parties, input byte limits
+alone are insufficient: aliases can expand during normalization. A bounded
+loader would need explicit limits for depth and expanded nodes as well as
+input size. Such limits should be opt-in initially to avoid silently changing
+the accepted configuration model. They are not implemented by this release;
+use the isolation and validation measures described above for those inputs.

{upref-2.1.0 → upref-2.2.0}/docs/storage.rst

@@ -92,6 +92,10 @@ kept in insertion order. YAML comments, anchors, aliases, quoting choices,
 and custom formatting are not part of the configuration model and are not
 preserved on save.
 
+Unicode NEL (U+0085) is escaped in quoted strings to prevent YAML line folding
+from changing it into a space. This applies to both keys and values; ordinary
+Unicode text remains readable.
+
 Applying selected changes
 -------------------------
 

upref-2.2.0/docs/user_preferences.rst

@@ -0,0 +1,172 @@
+User preference scenarios
+==========================
+
+These ten programs cover the lifecycle of preferences in a desktop or terminal
+application. They use only Upref and the Python standard library. Run them
+from an installed checkout, for example:
+
+.. code-block:: console
+
+   python examples/first_run_preferences.py
+   python examples/reset_preferences.py
+
+On Windows, ``.\.venv\Scripts\python.exe`` can replace ``python`` without
+activating the environment. Every file in these scenarios is temporary and
+removed on exit, so each invocation begins with fresh demonstration data.
+To adapt a recipe to real preferences, create ``ConfigStore("your-app")``
+without a temporary ``directory`` override and remove the demo's seed data.
+
+First-run setup
+----------------
+
+``first_run_preferences.py`` asks for theme, language, font size, and
+notifications using :class:`~upref.Field`. Parsers and validators reject invalid
+choices and out-of-range sizes. Press Enter four times to accept the defaults,
+or try ``purple`` as the theme and ``9`` as the font size to see retries.
+
+File presence marks completed setup in this recipe. No file is written if
+collection is cancelled. A second startup is simulated in the same process and
+reuses the saved preferences without asking again. Existing values are not
+business-validated on that path; see ``typed_settings.py`` when manually edited
+preferences need validation on every startup.
+
+.. literalinclude:: ../examples/first_run_preferences.py
+   :language: python
+
+Editing and applying a draft
+-----------------------------
+
+``apply_preferences.py`` starts with saved preferences and edits a detached
+draft. The final yes/no prompt defaults to ``False``: Enter discards the draft,
+``yes`` saves it, and Ctrl+C cancels the interaction. A language preference
+outside the editing schema survives a successful save.
+
+For example, enter ``dark``, ``20``, and ``yes`` to apply changes. Repeat with
+``no`` to observe the unchanged saved preferences. A load/edit/save interaction
+assumes one writer; applications with simultaneous writers must coordinate the
+whole operation as described in :doc:`storage`.
+
+.. literalinclude:: ../examples/apply_preferences.py
+   :language: python
+
+Resetting preferences
+-----------------------
+
+``reset_preferences.py`` removes a saved font-size override, then the entire
+appearance section, then the configuration file. The intermediate output shows
+that notifications remain disabled while appearance returns to defaults.
+
+Load the raw saved mapping when removing overrides. Loading with defaults and
+saving that result would persist those default values. Likewise,
+``update({"appearance": {}})`` does not clear a section because mappings merge
+recursively. Remove the key from the loaded mapping and save explicitly.
+
+.. literalinclude:: ../examples/reset_preferences.py
+   :language: python
+
+Recent documents
+------------------
+
+``recent_files.py`` normalizes paths, moves reopened documents to the front,
+and limits the history to two entries in the demonstration. The result is
+``['notes.txt', 'draft.md']``; the separate theme preference remains ``dark``.
+No document is opened or created. Existing history entries are assumed to have
+been normalized by this application; malformed lists are rejected before saving.
+
+.. literalinclude:: ../examples/recent_files.py
+   :language: python
+
+Window position and size
+--------------------------
+
+``window_preferences.py`` restores a window saved on a larger monitor into a
+1280 by 720 display. Invalid value types fall back to defaults; bounds are
+clamped so the restored window is visible. The example does not open a window.
+
+The geometry model uses the primary display's usable rectangle with origin
+``(0, 0)``. For multiple monitors, obtain the actual work areas and offsets from
+the GUI toolkit. Persist normal window bounds when closing, together with a
+separate maximized flag; minimized bounds are not useful restoration data.
+
+.. literalinclude:: ../examples/window_preferences.py
+   :language: python
+
+Several accounts in one application
+------------------------------------
+
+``account_preferences.py`` stores work and personal settings under separate
+account keys. Updating the work theme preserves the personal account. Unknown
+accounts receive defaults, and signing out removes the active selection while
+retaining the saved preferences.
+
+Account IDs are mapping keys, not filenames or credentials. These are accounts
+inside the same OS user's application, not an access-control boundary between
+different OS users. The recipe uses flat account preferences; nested defaults
+would need an explicit recursive merge strategy.
+
+.. literalinclude:: ../examples/account_preferences.py
+   :language: python
+
+Preferences for the current session
+------------------------------------
+
+``session_overrides.py`` makes precedence explicit: application defaults,
+saved preferences, then command-line options. Try:
+
+.. code-block:: console
+
+   python examples/session_overrides.py --theme dark --font-size 20
+   python examples/session_overrides.py --theme dark --remember
+
+The first command prints a dark session while saved preferences remain light.
+The second persists only the supplied theme override. It does not write every
+application default. Both commands operate inside a temporary demo directory,
+so ``--remember`` does not affect a later invocation of this example.
+
+.. literalinclude:: ../examples/session_overrides.py
+   :language: python
+
+Importing and exporting portable preferences
+---------------------------------------------
+
+``import_export_preferences.py`` exports only theme, language, and font size
+to JSON. Machine-local document history is excluded. Import rejects unknown
+keys, invalid values, duplicate keys, and malformed JSON before the application
+chooses to apply the preview. Boolean font sizes are rejected explicitly.
+
+The demonstration transfers preferences between two stores while preserving
+``['target-only.txt']`` as the target's local history. This is a small, local
+file exchange example; its JSON export uses an ordinary file write. Configuration
+persistence through ``ConfigStore`` continues to use atomic replacement.
+
+.. literalinclude:: ../examples/import_export_preferences.py
+   :language: python
+
+Backing up and restoring settings
+----------------------------------
+
+``backup_restore.py`` saves a value snapshot in a separate configuration file,
+changes preferences, then restores the snapshot. A missing or malformed backup
+raises before the current file is replaced. The backup itself remains unchanged.
+
+The snapshot preserves values rather than YAML comments or formatting. This
+single-writer recipe does not provide backup rotation or a transaction across
+the two files. Coordinate other writers when using it in a shared application.
+
+.. literalinclude:: ../examples/backup_restore.py
+   :language: python
+
+Previewing a legacy migration
+------------------------------
+
+``migration_preview.py`` creates a temporary legacy file with a reminder value
+and its unit. Automatic descriptor detection extracts the value but drops the
+unit. ``source_format="raw"`` preserves both.
+
+Both previews use ``dry_run=True`` and create no destination directory. The
+example then explicitly applies the raw conversion and verifies that the old
+file is unchanged. For migration of an actual v1 file, see ``migrate_v1.py``
+and :doc:`migration`.
+
+.. literalinclude:: ../examples/migration_preview.py
+   :language: python