[SashankBhamidi]

Closes #12. The release itself waits for calendaring-jmap 2.0.0 on PyPI and #37.

The adapter base is public now, in calendaring_sync.adapters.base. An adapter for a new protocol only writes how it reads changes and sends one edit, and gets the rest of a sync and the async variant from the base. Session moved to calendaring_sync.session, since replica.py was getting too long. Merge takes EditFields from the adapter's edit_fields(), otherwise a merge couldn't be fingerprinted the way the server's copy is.

The docs now have a quickstart, how-tos, a page on when to use it, and one on what it guarantees. Every code block is a file in docs/examples/ that the tests run and type-check, so they can't rot. Also Python 3.15, the latest pins, and a link check in CI.

From @niccokunzmann's reviews of #29 and #30, before anyone depends on the API:

• TakeServer and KeepEdit renamed to KeepServer and KeepLocal
• the record helpers moved onto Record: new(), with_copy(), synced_to(), removed_at()
• their own error classes for refusals that depend on what the store holds, plus LoneSurrogateError, all still ValueErrors
• typed thread-local state in the stores, and filtering by state in the base store
• fragments link to the reference

His points on resolutions and outcomes applying themselves, and on stores by composition, are bigger, so I'll open issues for those.

Fixed on the way: an edit refused for its logical key stayed a conflict even after the holder was gone. It goes back to pending now, but only once we actually see the key freed, so a UID held in another calendar can't make it loop.

Where I went a different way:

• The release prep is in here, not after the tag: the /en/stable/ links, the PyPI install, the PyPI icon. The links 404 until the tag.
• Restoring an older copy of the store makes new feed entries reuse numbers, so a cursor saved after the copy can skip some. Numbering by the clock made two identical syncs leave different feeds, so it's a documented limit for now.

I also renamed test_sync_integration.py to test_caldav_integration.py, since it only had the CalDAV tests.

Benchmarks against main are within noise, except JMAP fingerprints, about 7% slower from type-checking every event's EditFields.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[read-the-docs-community]

Documentation build overview

📚 calendaring-sync | 🛠️ Build #35441252 | 📁 Comparing 8539155 against latest (e41fe99)

  🔍 Preview build  

59 files changed · + 22 added · ± 37 modified

+ Added

• explanation/when-to-use.html
• how-to/async.html
• how-to/caldav.html
• how-to/change-feed.html
• how-to/conflicts.html
• how-to/errors.html
• how-to/every-calendar.html
• how-to/inspect.html
• how-to/jmap.html
• how-to/local-edits.html
• and 12 more...

± Modified

• changelog.html
• contribute.html
• genindex.html
• index.html
• py-modindex.html
• release.html
• security.html
• _modules/index.html
• explanation/adapters.html
• explanation/design.html
• and 27 more...