gonk.core.interfaces

class gonk.core.interfaces.Machine

Machine coordinates event validation and consumption.

validators: list[Validator]: Validators that have been registered.

consumers: list[Consumer]: Consumers that have been registered.

lock: DO NOT CONSIDER THIS THREAD SAFE WITHOUT FURTHER TESTING

process_event(event): Runs registered validators and consumers.

register(worker): Registers a class instance as a validator, consumer, or both.

class gonk.core.interfaces.Validator

Abstract class for validators.

abstract validate(event)

Validate the event.

Raises:: ValidationError – Invalid event.

class gonk.core.interfaces.Consumer

Abstract class for consumers.

abstract consume(event): Consume the event.

class gonk.core.interfaces.RecordKeeper

A RecordKeeper acts as the gonk.core.events.Event storage for the dataset.

validate(event: EventT)

Validate the event.

Raises:: ValidationError – Invalid event.

consume(event: EventT): Consume the event.

abstract add(event: EventT): Add a gonk.core.events.Event to storage.

abstract exists(uuid_: UUID) → bool: Check gonk.core.events.Event existence.

abstract read(uuid_: UUID) → Event

Read a gonk.core.events.Event from storage.

Raises:: ValueError – Event does not exist.

abstract next(uuid_: UUID | None) → UUID | None

Get the next gonk.core.events.Event’s: UUID in the event history.

Returns:

The next event UUID in the event history: or None if the provided UUID is the tail.

Raises:

ValueError – Event does not exist.

abstract tail() → UUID | None

Get the last gonk.core.events.Event’s: UUID in the event history.

Returns:

The last event UUID in the event history: or None when there are no events.

class gonk.core.interfaces.Depot

A Depot acts as the object (and annotation) storage for a dataset.

The Depot interface is a little clunky. It was designed to be compatible with S3’s multipart upload. This was done to enable working with very large objects as well as bittorrent-style block-based file sharing.

abstract exists(identifier: Identifier): Check whether an object exists.

abstract reserve(identifier: Identifier, size: int)

Reserve an object identifier for writing.

Raises:: StorageError – Identifier already exists.

abstract write(identifier: Identifier, offset: int, buf: bytes)

Write bytes to an object at an offset.

Raises:

StorageError – Identifier not found.
StorageError – Object finalized.

abstract finalize(identifier: Identifier)

Finalize an object and make it readable.

Raises:

StorageError – Identifier not found.
StorageError – Object already finalized.

abstract read(identifier: Identifier, offset: int, size: int)

Read size bytes of an object from offset.

Raises:

StorageError – Identifier not found.
StorageError – Object not yet finalized.

abstract purge(identifier: Identifier)

Delete the object.

Raises:: StorageError – Identifier not found.

class gonk.core.interfaces.SchemaInfo(name: str, uuid_: UUID, versions: int)

Informational class for schemas.

name: str: Schema name.

uuid: UUID: Schema UUID.

versions: int: Number of versions.

serialize() → dict: Serialize instance to dictionary.

class gonk.core.interfaces.ObjectInfo(uuid_: UUID, versions: int)

Informational class for gonk.core.events.Objects.

uuid: UUID: Object UUID.

versions: int: Number of versions.

serialize() → dict: Serialize instance to dictionary.

class gonk.core.interfaces.AnnotationInfo(uuid_: UUID, versions: int)

Informational class for gonk.core.events.Annotations.

uuid: UUID: Annotation UUID.

versions: int: Number of versions.

serialize() → dict: Serialize instance to dictionary.

class gonk.core.interfaces.EventInfo(uuid_: UUID, type_: str, review: None | str)

Informational class for gonk.core.events.Events.

uuid: UUID: Event UUID.

type: str: Event type (class name).

review: None | str

The review status of the event.

For unreviewable events, gonk.core.events.OwnerEvent and gonk.core.events.ReviewEvent, this field is None. For reviewable events, gonk.core.events.ObjectEvent and gonk.core.events.AnnotationEvent, this field can be PENDING, ACCEPTED, or REJECTED.

serialize() → dict: Serialize instance to dictionary.

class gonk.core.interfaces.NamedIdentifier(uuid_: UUID, version: int, name: str)

Return type for schemas and objects.

serialize() → dict: Serialize instance to dictionary.

class gonk.core.interfaces.State

The state interface tracks the current state of the dataset.

The information it stores in implementation dependent but must enable event validation as well as provide the API that the web service requires to run.

abstract events_by_object(identifier: Identifier) → list[EventInfo]: Get the events for a given object.

abstract events_by_annotation(identifier: Identifier) → list[EventInfo]: Get the events for a given annotation.

abstract events_all(after: None | UUID = None) → list[EventInfo]

Get a page of 25 events.

Parameters:: after – Event UUID to page after or None for the first page.

abstract annotations_all(uuid_: None | UUID = None, after: None | UUID = None) → list[AnnotationInfo]

Get a page of 25 annotations.

Only one of uuid_ and after may be provided.

Parameters:

uuid – The annotation UUID to get information about.
after – Annotation UUID to page after or None for the first page.

abstract annotations_by_object(object_identifier: Identifier) → list[AnnotationInfo]: Gets the annotations for a given object.

abstract annotations_by_status(status: str, after: None | UUID = None) → list[Identifier]

Gets the annotations for a given status.

Parameters:

status – pending, accepted, rejected, or deleted.
after – Annotation UUID to page after or None for the first page.

abstract annotation(identifier: Identifier) → Annotation | None: Get an Annotation for a given identifier.

abstract objects_all(uuid_: None | UUID = None, after: None | UUID = None) → list[ObjectInfo]

Get a page of 25 objects.

Only one of uuid_ and after may be provided.

Parameters:

uuid – The object UUID to get information about.
after – Object UUID to page after or None for the first page.

abstract objects_by_annotation(annotation_uuid: UUID) → list[Identifier]: Get the objects for a given annotation.

abstract objects_by_status(status: str, after: None | UUID = None) → list[Identifier]

Gets the objects for a given status.

Parameters:

status – pending, accepted, rejected, or deleted.
after – Object UUID to page after or None for the first page.

abstract object(identifier: Identifier) → Object | None: Get an Object for a given identifier.

abstract schemas_all(name: None | str = None) → list[SchemaInfo]

Get all schemas.

Parameters:: name – If provided only information about that schema will be returned.

abstract schemas_by_status(status: str, after: None | UUID = None) → list[NamedIdentifier]

Gets the schemas for a given status.

Parameters:

status – pending, accepted, rejected, or deprecated.
after – Schema UUID to page after or None for the first page.

abstract schema(name: str, version: int) → Object | None: Get a schema for a given name and version.

abstract owners() → list[str]: Get all owners.

validate(event: EventT): Dispatch method for event validation methods.

abstract _validate_object_create(event: ObjectCreateEvent)

Validate gonk.core.events.ObjectCreateEvent.

Raises:

ValidationError – Object UUID already exists.
ValidationError – Schema name already in use.
ValidationError – Duplicate hash detected.
ValidationError – Object version not zero.

abstract _validate_object_update(event: ObjectUpdateEvent)

Validate gonk.core.events.ObjectUpdateEvent.

Raises:

ValidationError – Object UUID does not exists.
ValidationError – Duplicate hash detected.
ValidationError – Schema name changed between versions.
ValidationError – Incorrect object version.

abstract _validate_object_delete(event: ObjectDeleteEvent)

Validate gonk.core.events.ObjectDeleteEvent.

Raises:

ValidationError – Object is a schema.
ValidationError – Object identifier not found.
ValidationError – Object is rejected.
ValidationError – Object pending deletion.
ValidationError – Object is deleted.

abstract _validate_annotation_create(event: AnnotationCreateEvent)

Validate gonk.core.events.AnnotationCreateEvent.

Raises:

ValidationError – Annotation UUID already exists.
ValidationError – Annotation version not zero.
ValidationError – Object identifier not found.
ValidationError – Annotating a rejected object.
ValidationError – Annotating a deleted object.
ValidationError – Annotating a schema.

abstract _validate_annotation_update(event: AnnotationUpdateEvent)

Validate gonk.core.events.AnnotationUpdateEvent.

Raises:

ValidationError – Annotation UUID does not exists.
ValidationError – Incorrect annotation version.

abstract _validate_annotation_delete(event: AnnotationDeleteEvent)

Validate gonk.core.events.AnnotationDeleteEvent.

Raises:

ValidationError – Annotation identifier not found.
ValidationError – Annotation is rejected.
ValidationError – Annotation pending deletion.
ValidationError – Annotation is deleted.

abstract _validate_review_accept(event: ReviewAcceptEvent)

Validate gonk.core.events.ReviewAcceptEvent.

Raises:

ValidationError – Event not found.
ValidationError – Event already reviewed.
ValidationError – Review of non object or annotation event.
ValidationError – Author is not owner.

abstract _validate_review_reject(event: ReviewRejectEvent)

Validate gonk.core.events.ReviewRejectEvent.

Raises:

ValidationError – Event not found.
ValidationError – Event already reviewed.
ValidationError – Review of non object or annotation event.
ValidationError – Author is not owner.

abstract _validate_owner_add(event: OwnerAddEvent)

Validate gonk.core.events.OwnerAddEvent.

Raises:

ValidationError – Owner already exists.
ValidationError – Author is not owner.
ValidationError – First owner add event must be a self add.

abstract _validate_owner_remove(event: OwnerRemoveEvent)

Validate gonk.core.events.OwnerRemoveEvent.

Raises:

ValidationError – No owners to remove.
ValidationError – Author is not owner.
ValidationError – Target of remove event is not an owner.
ValidationError – Cannot leave the dataset ownerless.
ValidationError – Target is a higher rank than author.

consume(event: EventT): Dispatch method for event consumption methods.

abstract _consume_object_create(event: ObjectCreateEvent): Consume gonk.core.events.ObjectCreateEvent.

abstract _consume_object_update(event: ObjectUpdateEvent): Consume gonk.core.events.ObjectUpdateEvent.

abstract _consume_object_delete(event: ObjectDeleteEvent): Consume gonk.core.events.ObjectDeleteEvent.

abstract _consume_annotation_create(event: AnnotationCreateEvent): Consume gonk.core.events.AnnotationCreateEvent.

abstract _consume_annotation_update(event: AnnotationUpdateEvent): Consume gonk.core.events.AnnotationUpdateEvent.

abstract _consume_annotation_delete(event: AnnotationDeleteEvent): Consume gonk.core.events.AnnotationDeleteEvent.

abstract _consume_review_accept(event: ReviewAcceptEvent): Consume gonk.core.events.ReviewAcceptEvent.

abstract _consume_review_reject(event: ReviewRejectEvent): Consume gonk.core.events.ReviewRejectEvent.

abstract _consume_owner_add(event: OwnerAddEvent): Consume gonk.core.events.OwnerAddEvent.

abstract _consume_owner_remove(event: OwnerRemoveEvent): Consume gonk.core.events.OwnerRemoveEvent.