objects: Change sets, records, scopes, and feed entries

The data an adapter hands the core, and what the core returns.

What an adapter hands the core after asking the server what changed.

class calendaring_sync.objects.change_set.ChangeSet(scope: str, since: str | None, token: str, changes: Mapping[str, Changed | Removed | Unchanged], full_listing: bool = False, truncated: bool = False)

Bases: object

One change set, or one truncated page of it, for one scope.

Variables:

• scope (str) – The id of the scope it covers.

• since (str | None) – The sync token it was fetched from, None for a scope that has none. Every page of a full listing carries the scope’s token from before the listing.

• token (str) – The token the scope moves to. On a truncated page of an incremental change set that’s the page’s checkpoint. Every page of a full listing carries the same token, the one the listing read before it started, and the scope moves to it when the last page is ingested.

• changes (collections.abc.Mapping[str, calendaring_sync.objects.change.Changed | calendaring_sync.objects.change.Removed | calendaring_sync.objects.change.Unchanged]) – Each object id mapped to how the object changed. An object appears once.

• full_listing (bool) – Whether it lists every object in the scope, rather than only what changed.

• truncated (bool) – Whether more pages follow it.

changes: Mapping[str, Changed | Removed | Unchanged]

full_listing: bool = False

scope: str

since: str | None

token: str

truncated: bool = False

The three ways an object can appear in a change set.

calendaring_sync.objects.change.Change = calendaring_sync.objects.change.Changed | calendaring_sync.objects.change.Removed | calendaring_sync.objects.change.Unchanged

Any one of the three.

class calendaring_sync.objects.change.Changed(version: str | None, fingerprint: str, content: str, containers: frozenset[str] = frozenset({}), logical_key: str | None = None)

Bases: object

The object changed on the server, or is new there.

Variables:

• version (str | None) – The object’s version, or None if the server gives none.

• fingerprint (str) – The object’s fingerprint, computed by the adapter.

• content (str) – The object’s content, exactly as the server sent it.

• containers (frozenset[str]) – The containers the object belongs to.

• logical_key (str | None) – The object’s logical key, if it has one.

containers: frozenset[str] = frozenset({})

content: str

fingerprint: str

logical_key: str | None = None

version: str | None

class calendaring_sync.objects.change.Removed

Bases: object

The object is gone from the server.

class calendaring_sync.objects.change.Unchanged

Bases: object

The object hasn’t changed since the version the store holds.

Only a full listing reports this, so the object isn’t fetched again.

A record: everything the core stores about one object.

class calendaring_sync.objects.record.Record(local_key: int, scope: str, object_id: str | None, state: RecordState, version: str | None, fingerprint: str | None, content: str, containers: frozenset[str], logical_key: str | None, synced_at: datetime | None, last_entry: int)

Bases: object

One record.

Variables:

• local_key (int) – The local key the core gave the record. It never changes, and is never given to another record.

• scope (str) – The id of the scope the record belongs to.

• object_id (str | None) – The object id, or None until the server assigns one to an object you created.

• state (calendaring_sync.objects.record.RecordState) – The record’s state.

• version (str | None) – The object’s version, or None.

• fingerprint (str | None) – The fingerprint of content, or None after a fingerprint scheme change until the object is listed again.

• content (str) – The object’s synced content.

• containers (frozenset[str]) – The containers the object belongs to.

• logical_key (str | None) – The object’s logical key, if it has one.

• synced_at (datetime.datetime | None) – When an ingest last applied a change to the record, or None if none has.

• last_entry (int) – The number of the last change feed entry about the record, 0 if there’s none.

containers: frozenset[str]

content: str

fingerprint: str | None

last_entry: int

local_key: int

logical_key: str | None

object_id: str | None

scope: str

state: RecordState

synced_at: datetime | None

version: str | None

class calendaring_sync.objects.record.RecordState(*values)

Bases: StrEnum

The five states a record can be in.

CONFLICT = 'conflict'

Holds an open conflict.

IN_FLIGHT = 'in_flight'

Its push was sent, and how it ended isn’t known yet.

PENDING = 'pending'

Holds a pending edit.

REMOVED = 'removed'

Gone from the server, kept until it’s purged.

SYNCED = 'synced'

Matches the server’s copy.

A scope as the store keeps it.

class calendaring_sync.objects.scope.Scope(id: str, token: str | None, fingerprint_scheme: str, media_type: str, last_sync_at: datetime | None = None, last_full_listing_at: datetime | None = None, listing_token: str | None = None)

Bases: object

One scope.

Variables:

• id (str) – The id the adapter gave the scope.

• token (str | None) – The scope’s sync token, or None before its first full listing finishes and after a reset.

• fingerprint_scheme (str) – The fingerprint scheme of the scope’s records.

• media_type (str) – The media type of the scope’s content.

• last_sync_at (datetime.datetime | None) – When an ingest of the scope last finished, or None.

• last_full_listing_at (datetime.datetime | None) – When a full listing of the scope last finished, or None.

• listing_token (str | None) – The token of the full listing in progress, or None. A page of any other listing is refused, so two processes listing the scope at once can’t mix their results.

fingerprint_scheme: str

id: str

last_full_listing_at: datetime | None = None

last_sync_at: datetime | None = None

listing_token: str | None = None

media_type: str

token: str | None

An entry in the change feed.

class calendaring_sync.objects.feed.FeedEntry(number: int, scope: str, kind: FeedEntryKind, local_key: int | None, object_id: str | None, at: datetime)

Bases: object

One feed entry.

Variables:

• number (int) – The entry’s number. Each entry’s is larger than the one before it.

• scope (str) – The id of the scope the entry is about.

• kind (calendaring_sync.objects.feed.FeedEntryKind) – What happened.

• local_key (int | None) – The local key of the record the entry is about, None for a dropped scope. The record may since have been purged.

• object_id (str | None) – The record’s object id when the entry was written, None for a dropped scope.

• at (datetime.datetime) – When the entry was written.

at: datetime

kind: FeedEntryKind

local_key: int | None

number: int

object_id: str | None

scope: str

class calendaring_sync.objects.feed.FeedEntryKind(*values)

Bases: StrEnum

What a feed entry records.

CHANGED = 'changed'

the object is new, changed, or back on the server.

Type:

A remote change was applied

REMOVED = 'removed'

A remote removal was applied.

SCOPE_DROPPED = 'scope_dropped'

A scope was dropped, with every record in it.

What drop_scope() discards.

class calendaring_sync.objects.dropped_scope.DroppedScope(scope: str, pending: tuple[Record, ...], conflicts: tuple[Record, ...])

Bases: object

The local work a drop discarded, for your application to save or show.

Variables:

• scope (str) – The id of the dropped scope.

• pending (tuple[calendaring_sync.objects.record.Record, ...]) – The records that held a pending edit, including ones in flight.

• conflicts (tuple[calendaring_sync.objects.record.Record, ...]) – The records that held an open conflict.

conflicts: tuple[Record, ...]

pending: tuple[Record, ...]

scope: str

See Errors for the exception hierarchy.