Stores built from a storage, and resolutions that apply themselves by SashankBhamidi · Pull Request #41 · PyCalendar/calendaring-sync

SashankBhamidi · 2026-10-28T19:28:29Z

Closes #39.
Closes #40.

From @niccokunzmann's reviews of #29 and #30, done before the release so nothing needs a deprecation later.

A store is a StateStore over a Storage now. A new storage implements Storage and StorageTransaction, both with public names, and gets every check from the store. A MemoryKeeper replaces subclassing MemoryStore to keep its data in a file.

Resolutions and push outcomes decide their own effect, so the replica has no match on them anymore. Nothing public changed, and no test either.

Also the three fixes I promised in the threads, and resolve_conflicts returns the conflicts it resolved, left open or found changed, instead of a count.

Fixed: a failed rollback replaced the block's own error, so Ctrl-C came out as UnexpectedStoreError.

The adapter hooks keep their underscores: the app calls sync() on the adapter, and a public read() or send() next to it would skip the session.

codecov · 2026-10-28T19:29:45Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

read-the-docs-community · 2026-10-28T19:30:57Z

Documentation build overview

📚 calendaring-sync | 🛠️ Build #35480326 | 📁 Comparing b41eae6 against latest (f66613e)

🔍 Preview build

28 files changed · ± 28 modified

± Modified

Copilot

🟡 Changes recommended

The changes can destroy saved state when the destination already ends in .new and allow post-construction mapping mutations to bypass validation, accepting invalid incremental entries and advancing the scope token.

2 open issues

What changed in this PR

Refactors storage and conflict handling to support new backends without subclass hooks and move resolution behavior out of Replica, addressing #39 and #40.

Changes:

Introduces public storage interfaces and optional MemoryKeeper persistence.
Moves resolution and push-outcome behavior into their value classes and returns detailed conflict-resolution results.
Updates validation, transaction error handling, tests, examples, and documentation.

File	Description
`src/calendaring_sync/tests/test_sync_unit.py`	Updates interface tests and adds failure-path coverage.
`src/calendaring_sync/tests/conftest.py`	Adds a custom-storage test fixture.
`src/calendaring_sync/tests/_storage.py`	Adds a minimal storage implementation for tests.
`src/calendaring_sync/store/sqlite.py`	Separates SQLite storage and transaction operations.
`src/calendaring_sync/store/memory.py`	Adds memory storage transactions and keeper persistence.
`src/calendaring_sync/store/base.py`	Defines storage interfaces and centralizes store safeguards.
`src/calendaring_sync/store/__init__.py`	Updates the package description.
`src/calendaring_sync/session.py`	Delegates push-outcome validation.
`src/calendaring_sync/replica.py`	Delegates effects and reports conflict-resolution results.
`src/calendaring_sync/objects/resolution.py`	Implements resolution behavior and result fields.
`src/calendaring_sync/objects/record.py`	Clarifies copy terminology in documentation.
`src/calendaring_sync/objects/push.py`	Implements push-outcome checks and effects.
`src/calendaring_sync/objects/feed.py`	Clarifies a feed-entry comment.
`src/calendaring_sync/objects/edit.py`	Updates synced-copy terminology.
`src/calendaring_sync/objects/conflict.py`	Clarifies conflict documentation.
`src/calendaring_sync/objects/change_set.py`	Validates incremental entries during construction.
`src/calendaring_sync/objects/_data.py`	Updates shared-field comments.
`src/calendaring_sync/error.py`	Clarifies stale-conflict documentation.
`src/calendaring_sync/adapters/base.py`	Explains underscored adapter hooks.
`src/calendaring_sync/_classify.py`	Updates classifier documentation terminology.
`src/calendaring_sync/__init__.py`	Exports new storage and result types.
`news/9.feature.rst`	Documents detailed conflict-resolution results.
`news/40.feature.rst`	Announces storage composition.
`news/28.feature.rst`	Documents keeper-based persistence.
`docs/reference/store.rst`	Documents the new public storage interfaces.
`docs/reference/guarantees.rst`	Updates the concurrent-read capability reference.
`docs/reference/glossary.rst`	Defines storage and copy terminology.
`docs/how-to/store.rst`	Explains keepers and custom storage.
`docs/how-to/mirror.rst`	Clarifies mirrored-copy terminology.
`docs/how-to/conflicts.rst`	Explains conflict-resolution results.
`docs/explanation/design.rst`	Updates storage architecture and conflict terminology.
`docs/examples/keeper.py`	Adds a file-backed keeper example.
`docs/contribute.rst`	Updates the storage module description.
`docs/conf.py`	Hides private bases in generated documentation.

_{Review effort: Balanced}

SashankBhamidi · 2026-10-28T19:45:11Z

            for object_id, change in change_set.changes.items():
-                if not change_set.full_listing and isinstance(change, Unchanged):
-                    raise ValueError(f"Unchanged object {object_id!r} outside a full listing")
                self._apply(scope.id, object_id, change, now, claimed, freed)


Fixed in b41eae6 differently: ChangeSet now keeps its own read-only copy, so later changes to the mapping never reach it.

…orary file apart

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

SashankBhamidi added 2 commits October 28, 2026 16:57

feat: build stores from a storage and settle the core API before release

34d9436

refactor: let resolutions and push outcomes apply themselves

3c1ea9f

SashankBhamidi requested a review from stevepiercy as a code owner October 28, 2026 19:28

SashankBhamidi requested a balanced review from Copilot and removed request for stevepiercy October 28, 2026 19:30

Copilot started reviewing on behalf of SashankBhamidi October 28, 2026 19:31

View session

Copilot AI reviewed Oct 28, 2026

View reviewed changes

fix: keep a change set's own copy of its changes, and a keeper's temp…

b41eae6

…orary file apart

SashankBhamidi requested a balanced review from Copilot October 28, 2026 19:45

Copilot AI reviewed Oct 28, 2026

SashankBhamidi merged commit 6ae13db into main Oct 28, 2026
15 checks passed

SashankBhamidi deleted the feat/storage-strategy branch October 28, 2026 19:48

Navigation Menu

Repository navigation

Stores built from a storage, and resolutions that apply themselves - #41

Stores built from a storage, and resolutions that apply themselves#41
SashankBhamidi merged 3 commits into
mainfrom
feat/storage-strategy

SashankBhamidi commented Oct 28, 2026

Uh oh!

codecov Bot commented Oct 28, 2026

Uh oh!

read-the-docs-community Bot commented Oct 28, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

SashankBhamidi Oct 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

SashankBhamidi commented Oct 28, 2026

Uh oh!

codecov Bot commented Oct 28, 2026

Codecov Report

Uh oh!

read-the-docs-community Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

SashankBhamidi Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

read-the-docs-community Bot commented Oct 28, 2026 •

edited

Loading