cayu.tasks.scheduling

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

TaskMisfirePolicy

from cayu.tasks import TaskMisfirePolicy

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
FIRE_ONCE	class attribute	'fire_once'
SKIP	class attribute	'skip'

Release source · Runtime guarantees · Capability guides

TaskRescheduleRequest

from cayu.tasks import TaskRescheduleRequest

Replace a not-yet-admitted schedule at one expected revision.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
task_id	str	required
operation_id	str	required
expected_revision	StrictInt	Field(ge=1, le=MAX_PORTABLE_JSON_INTEGER)
available_at	datetime	required
policy	TaskSchedulePolicy	Field(default_factory=TaskSchedulePolicy)

validate_identity (method)

TaskRescheduleRequest.validate_identity(value: str, info) -> str

normalize_availability (method)

TaskRescheduleRequest.normalize_availability(value: datetime) -> datetime

copy_policy (method)

TaskRescheduleRequest.copy_policy(value: object) -> object

validate_window (method)

TaskRescheduleRequest.validate_window() -> TaskRescheduleRequest

Release source · Runtime guarantees · Capability guides

TaskScheduleCancelRequest

from cayu.tasks import TaskScheduleCancelRequest

Cancel one exact schedule revision without bypassing a live worker.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
task_id	str	required
operation_id	str	required
expected_revision	StrictInt	Field(ge=1, le=MAX_PORTABLE_JSON_INTEGER)

validate_identity (method)

TaskScheduleCancelRequest.validate_identity(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

TaskScheduleConflict

from cayu.tasks import TaskScheduleConflict

A scheduling operation does not match the current or retained authority.

Bases: ValueError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

TaskScheduleEligibility

from cayu.tasks import TaskScheduleEligibility

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
FUTURE	class attribute	'future'
ELIGIBLE	class attribute	'eligible'
MISFIRED	class attribute	'misfired'
EXPIRED	class attribute	'expired'
SKIPPED	class attribute	'skipped'

Release source · Runtime guarantees · Capability guides

TaskScheduleEvent

from cayu.tasks import TaskScheduleEvent

Task-owned evidence; it exists even before a session is attached.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
task_id	str	required
sequence	StrictInt	Field(ge=1, le=MAX_PORTABLE_JSON_INTEGER)
type	TaskScheduleEventType	required
revision	StrictInt	Field(ge=1, le=MAX_PORTABLE_JSON_INTEGER)
occurred_at	datetime	required
available_at	datetime	required
policy	TaskSchedulePolicy	required
invocation_id	str	required
operation_id	str | None	None

validate_identity (method)

TaskScheduleEvent.validate_identity(value: str | None, info) -> str | None

normalize_time (method)

TaskScheduleEvent.normalize_time(value: datetime, info) -> datetime

copy_policy (method)

TaskScheduleEvent.copy_policy(value: object) -> object

Release source · Runtime guarantees · Capability guides

TaskScheduleEventType

from cayu.tasks import TaskScheduleEventType

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
SCHEDULED	class attribute	'task.scheduled'
RESCHEDULED	class attribute	'task.rescheduled'
ELIGIBLE	class attribute	'task.schedule_eligible'
MISFIRED	class attribute	'task.schedule_misfired'
EXPIRED	class attribute	'task.schedule_expired'
SKIPPED	class attribute	'task.schedule_skipped'
DEPENDENCY_SKIPPED	class attribute	'task.schedule_dependency_skipped'
CLAIMED	class attribute	'task.schedule_claimed'
CANCELLATION_REQUESTED	class attribute	'task.schedule_cancellation_requested'
CANCELLED	class attribute	'task.schedule_cancelled'
STARTED	class attribute	'task.schedule_started'
HELD	class attribute	'task.schedule_held'
RESUMED	class attribute	'task.schedule_resumed'
COMPLETED	class attribute	'task.schedule_completed'
FAILED	class attribute	'task.schedule_failed'

Release source · Runtime guarantees · Capability guides

TaskSchedulePolicy

from cayu.tasks import TaskSchedulePolicy

An optional latest admission time and deterministic late-arrival policy.

expires_at is exclusive. A task observed exactly at expiry cannot be admitted. Lateness strictly greater than the grace interval is a misfire; equality stays eligible. Expiry takes precedence over the misfire policy.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
expires_at	datetime | None	None
misfire_policy	TaskMisfirePolicy	TaskMisfirePolicy.FIRE_ONCE
misfire_grace_seconds	StrictInt	Field(default=60, ge=0, le=TASK_SCHEDULE_GRACE_MAX_SECONDS)

normalize_expiry (method)

TaskSchedulePolicy.normalize_expiry(value: datetime | None) -> datetime | None

Release source · Runtime guarantees · Capability guides

TaskScheduleReceipt

from cayu.tasks import TaskScheduleReceipt

Immutable accepted mutation; replay never overwrites the live schedule.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
task_id	str	required
operation_id	str	required
request_sha256	str	Field(pattern='^[0-9a-f]{64}$')
expected_revision	StrictInt	Field(ge=1, le=MAX_PORTABLE_JSON_INTEGER)
schedule	TaskScheduleState	required
available_at	datetime	required
committed_at	datetime	required
type	Literal[TaskScheduleEventType.RESCHEDULED, TaskScheduleEventType.CANCELLATION_REQUESTED, TaskScheduleEventType.CANCELLED]	required

validate_identity (method)

TaskScheduleReceipt.validate_identity(value: str, info) -> str

normalize_time (method)

TaskScheduleReceipt.normalize_time(value: datetime, info) -> datetime

copy_schedule (method)

TaskScheduleReceipt.copy_schedule(value: object) -> object

validate_successor (method)

TaskScheduleReceipt.validate_successor() -> TaskScheduleReceipt

Release source · Runtime guarantees · Capability guides

TaskScheduleState

from cayu.tasks import TaskScheduleState

Current schedule authority embedded in the durable task snapshot.

The original creation digest survives rescheduling and terminalization. First admission permanently ends eligibility expiry: lease reclaim does not turn an already-dispatched task into a new scheduled occurrence.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal[1]	1
revision	StrictInt	Field(default=1, ge=1, le=MAX_PORTABLE_JSON_INTEGER)
policy	TaskSchedulePolicy	required
creation_sha256	str	Field(pattern='^[0-9a-f]{64}$')
admitted_at	datetime | None	None

copy_policy (method)

TaskScheduleState.copy_policy(value: object) -> object

normalize_admission (method)

TaskScheduleState.normalize_admission(value: datetime | None) -> datetime | None

Release source · Runtime guarantees · Capability guides

TaskScheduleWakeup

from cayu.tasks import TaskScheduleWakeup

A bounded, content-free store observation, never permission to dispatch.

The store applies the worker’s actual claim filters. next_available_at is absent when no matching unadmitted future task exists. Expired/skipped work may require a sweep even when no task will become runnable.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
as_of	datetime	required
next_available_at	datetime | None	None
next_expiry_at	datetime | None	None
maintenance_required	StrictBool	False

normalize_time (method)

TaskScheduleWakeup.normalize_time(value: datetime | None, info) -> datetime | None

Release source · Runtime guarantees · Capability guides