ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

class documentation

Register scheduled tasks and coordinate their scheduler integration.

Method __addConfiguredJobStore Register the configured database or Redis job store.
Method __controlFailure Report a scheduler control failure and return its error.
Method __createManagedTask Create a supervised asyncio task and retain it until completion.
Async Method __drainListeners Await the current listener snapshot without awaiting its shutdown owner.
Async Method __drainTasks Collect owned futures and observe failures without abandoning cleanup.
Async Method __finishShutdown Await native shutdown, job cleanup and late lifecycle listeners.
Async Method __gracefulShutdown Finalize shutdown and preserve failures for waiting callers.
Async Method __handleListenerException Report a scheduler failure through runtime or legacy handling.
Async Method __handleTaskException Report a task execution failure independently of event listeners.
Method __init__ Initialize scheduler dependencies, task registries, and shutdown state.
Async Method __loadAvailableCommands Cache command signatures exposed by the reactor.
Method __shutdownCompleted Notify shutdown waiters if the managed shutdown task was cancelled.
Async Method __startScheduler Build and start one native backend under the lifecycle lock.
Method __suppressApschedulerLogging Disable APScheduler loggers and their message propagation.
Async Method __validateAndLoadFluentTasks Validate fluent task signatures and build their task entities.
Method _dispatchSchedulerEventListener Dispatch a scheduler event to its registered listener.
Method _dispatchTaskEventListener Observe task failures and dispatch the matching event listener.
Async Method boot Initialize and start the scheduler with configured tasks and listeners.
Method command Declare a command for fluent scheduling configuration.
Async Method info Return scheduling metadata for all validated tasks.
Method isPaused Check whether the scheduler is paused.
Method isRunning Check whether the scheduler is running.
Method isStopped Check whether the scheduler is stopped.
Method on Register or replace a listener for a scheduler lifecycle event.
Method pause Pause scheduling when the scheduler is running.
Method pauseTask Pause a running task by its signature.
Method removeAllTasks Remove all tasks from the scheduler.
Method removeTask Remove a tracked task from the scheduler.
Method resume Resume scheduling when the scheduler is paused.
Method resumeTask Resume a paused task by its signature.
Method shutdown Schedule graceful shutdown without blocking the caller.
Method state Return the current scheduler state value.
Async Method wait Wait for shutdown completion and re-raise any retained failure.
Constant _SCHEDULER_NOT_STARTED_ERROR The Orionis task scheduler has not been started..
Instance Variable __available_command_signatures Available command signatures produced by set.
Instance Variable __boot_lock Serialize native scheduler creation and closure.
Instance Variable __config Validated configuration used to construct and operate the service.
Instance Variable __exception_handler Exception handler for managing errors.
Instance Variable __failure_runtime Application runtime retained for callbacks outside the starting context.
Instance Variable __fluent_tasks Task declarations awaiting conversion to scheduler jobs.
Instance Variable __job_store Job store obtained from self.__config.store.
Instance Variable __paused_tasks Paused tasks produced by set.
Instance Variable __pending_listener_tasks Pending listener tasks produced by set.
Instance Variable __reactor Reactor instance for command execution.
Instance Variable __removed_tasks Removed tasks produced by set.
Instance Variable __running_tasks Running tasks produced by set.
Instance Variable __scheduler Scheduler instance responsible for registering and running tasks.
Instance Variable __scheduler_listeners Callbacks subscribed to scheduler lifecycle events.
Instance Variable __shutdown_error Failure retained for the caller awaiting shutdown completion.
Instance Variable __shutdown_event Notify callers when scheduler shutdown settles.
Instance Variable __shutdown_task Single shutdown operation owned by the current scheduler cycle.
Instance Variable __state State selected by the maintenance-mode command.
Instance Variable __stores Schedule store for managing job stores.
Instance Variable __tasks Tasks registered for scheduling or lifecycle management.
Instance Variable __tasks_listeners Callbacks subscribed to scheduled-task events.
Instance Variable __wait_to_shutdown Wait to shutdown value used by Schedule.
def __addConfiguredJobStore(self: Self): (source)

Register the configured database or Redis job store.

Leave the in-memory store unchanged when no persistent driver is selected.

Returns
NoneAdd the selected persistent store to the scheduler.
Raises
RuntimeErrorIf persistent-store configuration is missing or its backend is unsupported.
def __controlFailure(self, message: str, action: str) -> RuntimeError: (source)

Report a scheduler control failure and return its error.

Parameters
message:strMessage describing the failed scheduler operation.
action:strControl-method name attached to the failure report.
Returns
RuntimeErrorNew error carrying the supplied message.
def __createManagedTask(self: Self, coroutine: Coroutine) -> asyncio.Task: (source)

Create a supervised asyncio task and retain it until completion.

Parameters
coroutine:collections.abc.CoroutineCoroutine to execute and close if its supervisor never starts.
Returns
asyncio.TaskTask supervised for failures and removed from the pending set when complete.
async def __drainListeners(self): (source)

Await the current listener snapshot without awaiting its shutdown owner.

Returns
NoneNo return value.
async def __drainTasks(self, pending: tuple[asyncio.Future[object], ...]): (source)

Collect owned futures and observe failures without abandoning cleanup.

Parameters
pending:tuple of asyncio.FutureOwned jobs or listeners whose completion must be collected.
Returns
NoneNo return value.
async def __finishShutdown(self: Self): (source)

Await native shutdown, job cleanup and late lifecycle listeners.

Wait for the configured grace period before draining pending listeners. The worker bridge returns only after the native loop callback finishes.

Returns
NoneComplete native shutdown and owned asynchronous cleanup.
async def __gracefulShutdown(self: Self): (source)

Finalize shutdown and preserve failures for waiting callers.

Returns
NoneRun shutdown, retain any failure, and always notify shutdown waiters.
Raises
BaseExceptionIf shutdown is cancelled or raises another non-Exception error.
async def __handleListenerException(self: Self, exception: Exception, *, legacy: bool = True): (source)

Report a scheduler failure through runtime or legacy handling.

Parameters
exception:ExceptionException raised by a scheduled operation or event listener.
legacy:bool, default TrueAllow the configured exception handler as a fallback; log instead when False.
Returns
NoneCapture the failure or apply the selected fallback reporting path.
async def __handleTaskException(self: Self, exception: BaseException, signature: str): (source)

Report a task execution failure independently of event listeners.

Parameters
exception:BaseExceptionExecution error reported by the scheduler.
signature:strCommand signature associated with the failed job.
Returns
NoneCapture the error and use fallback reporting for ordinary exceptions when runtime reporting is unavailable.
def __init__(self: Self, reactor: IReactor, exception_handler: ICatch, stores: IScheduleStore): (source)

Initialize scheduler dependencies, task registries, and shutdown state.

Parameters
reactor:orionis.console.core.contracts.reactor.IReactorCommand dispatcher used to discover available signatures.
exception_handler:orionis.failure.contracts.catch.ICatchFallback handler for event-listener failures.
stores:orionis.console.contracts.store.IScheduleStoreJob-store factory providing the scheduler configuration.
Returns
NoneStore dependencies and prepare a stopped scheduler.
async def __loadAvailableCommands(self: Self): (source)

Cache command signatures exposed by the reactor.

Skip discovery when the signature cache is already populated.

Returns
NoneUpdate the internal set of available command signatures.
def __shutdownCompleted(self, task: asyncio.Task): (source)

Notify shutdown waiters if the managed shutdown task was cancelled.

Parameters
task:asyncio.TaskCompleted shutdown supervisor task.
Returns
NoneRecord cancellation and signal completion if shutdown has not done so.
async def __startScheduler(self): (source)

Build and start one native backend under the lifecycle lock.

Returns
NoneNo return value.
def __suppressApschedulerLogging(self: Self): (source)

Disable APScheduler loggers and their message propagation.

Returns
NoneSet scheduler component loggers to CRITICAL and disable them.
async def __validateAndLoadFluentTasks(self: Self): (source)

Validate fluent task signatures and build their task entities.

Returns
NonePopulate the task registry using configured scheduling defaults.
Raises
ValueErrorIf a task signature is unavailable in the reactor.
def _dispatchSchedulerEventListener(self: Self, event: APSchedulerEvent): (source)

Dispatch a scheduler event to its registered listener.

Parameters
event:apscheduler.events.SchedulerEventLifecycle event to wrap for the listener.
Returns
NoneInvoke a synchronous listener or supervise an asynchronous listener, reporting failures. Do nothing when no listener is registered.
def _dispatchTaskEventListener(self: Self, event: APJobEvent): (source)

Observe task failures and dispatch the matching event listener.

Parameters
event:apscheduler.events.JobEventJob event containing a task signature and execution metadata.
Returns
NoneUpdate removal bookkeeping, report execution failures, and invoke the registered listener when present.
async def boot(self: Self): (source)

Initialize and start the scheduler with configured tasks and listeners.

Returns
NoneRegister job stores, jobs, and event dispatchers, then start scheduling.
Raises
ValueErrorIf a task signature is unavailable in the reactor.
RuntimeErrorIf a selected job store lacks required configuration or a supported backend, or shutdown is still in progress.
def command(self: Self, signature: str, args: list[str] | None = None, purpose: str | None = None) -> ITask: (source)

Declare a command for fluent scheduling configuration.

Replace any existing fluent declaration with the same signature.

Parameters
signature:strNon-empty command signature to schedule.
args:list[str] or None, optionalCommand-line tokens; use an empty list when None.
purpose:str or None, optionalHuman-readable description of the scheduled command.
Returns
orionis.console.fluent.contracts.task.ITaskFluent task definition for configuring timing and listeners.
Raises
RuntimeErrorIf the scheduler is not stopped.
TypeErrorIf the signature is blank or not a string, or arguments are not a list of strings or None.
async def info(self: Self) -> list[dict]: (source)

Return scheduling metadata for all validated tasks.

Returns
list[dict]Task metadata with start_date and end_date formatted as YYYY-MM-DD HH:MM:SS, or None when unset.
Raises
ValueErrorIf a task signature is unavailable in the reactor.
def isPaused(self: Self) -> bool: (source)

Check whether the scheduler is paused.

Returns
boolTrue when the scheduler state is PAUSED, otherwise False.
def isRunning(self: Self) -> bool: (source)

Check whether the scheduler is running.

Returns
boolTrue when the scheduler state is RUNNING, otherwise False.
def isStopped(self: Self) -> bool: (source)

Check whether the scheduler is stopped.

Returns
boolTrue when the scheduler state is STOPPED, otherwise False.
def on(self: Self, event: SchedulerEvent, listener: Callable) -> Self: (source)

Register or replace a listener for a scheduler lifecycle event.

Parameters
event:orionis.console.enums.events.SchedulerEventScheduler lifecycle event to observe.
listener:collections.abc.CallableSynchronous or asynchronous callback receiving a scheduler event entity.
Returns
typing.SelfThis scheduler for chained configuration.
Raises
RuntimeErrorIf the scheduler is not stopped.
TypeErrorIf event is not a scheduler event or listener is not callable.
def pause(self: Self) -> bool: (source)

Pause scheduling when the scheduler is running.

Returns
boolTrue after pausing the scheduler and updating its state.
Raises
RuntimeErrorIf the scheduler is uninitialized, is not running, or cannot be paused.
def pauseTask(self: Self, signature: str) -> bool: (source)

Pause a running task by its signature.

Parameters
signature:strSignature of the running task to pause.
Returns
boolTrue after pausing the job and updating task bookkeeping.
Raises
RuntimeErrorIf the scheduler is uninitialized, the task is not running, or the pause operation fails.
ValueErrorIf the scheduler cannot find the tracked job.
def removeAllTasks(self: Self) -> bool: (source)

Remove all tasks from the scheduler.

Returns
boolTrue after removing all jobs and clearing active task bookkeeping.
Raises
RuntimeErrorIf the scheduler is uninitialized or the removal operation fails.
def removeTask(self: Self, signature: str) -> bool: (source)

Remove a tracked task from the scheduler.

Parameters
signature:strSignature of the running or paused task to remove.
Returns
boolTrue after removing the job and updating task bookkeeping.
Raises
RuntimeErrorIf the scheduler is uninitialized, the task is not tracked as running or paused, or the removal operation fails.
ValueErrorIf the scheduler cannot find the tracked job.
def resume(self: Self) -> bool: (source)

Resume scheduling when the scheduler is paused.

Returns
boolTrue after resuming the scheduler and updating its state.
Raises
RuntimeErrorIf the scheduler is uninitialized, is not paused, or cannot be resumed.
def resumeTask(self: Self, signature: str) -> bool: (source)

Resume a paused task by its signature.

Parameters
signature:strSignature of the paused task to resume.
Returns
boolTrue after resuming the job and updating task bookkeeping.
Raises
RuntimeErrorIf the scheduler is uninitialized, the task is not paused, or the resume operation fails.
ValueErrorIf the scheduler cannot find the tracked job.
def shutdown(self: Self, wait: int | None = None): (source)

Schedule graceful shutdown without blocking the caller.

Start at most one shutdown task per scheduler boot cycle. The task observes a grace period, drains managed listeners, and requests scheduler shutdown.

Parameters
wait:int or None, optionalNon-negative grace period in seconds. Keep the current period when None; the initial default is 0.5 seconds.
Returns
NoneStart or reuse the managed shutdown task without waiting for completion.
Raises
TypeErrorIf wait is negative, a boolean, or neither an integer nor None.
def state(self: Self) -> str: (source)

Return the current scheduler state value.

Returns
strRUNNING, PAUSED, or STOPPED.
async def wait(self: Self): (source)

Wait for shutdown completion and re-raise any retained failure.

Returns
NoneReturn once shutdown completes successfully.
Raises
BaseExceptionIf shutdown failed or its task was cancelled.
_SCHEDULER_NOT_STARTED_ERROR: str = (source)

The Orionis task scheduler has not been started..

Value
'The Orionis task scheduler has not been started.'
__available_command_signatures: set[str] = (source)

Available command signatures produced by set.

__boot_lock = (source)

Serialize native scheduler creation and closure.

__config: ConfigScheduler = (source)

Validated configuration used to construct and operate the service.

__exception_handler: ICatch = (source)

Exception handler for managing errors.

__failure_runtime = (source)

Application runtime retained for callbacks outside the starting context.

__fluent_tasks: dict[str, ITask] = (source)

Task declarations awaiting conversion to scheduler jobs.

__job_store: str = (source)

Job store obtained from self.__config.store.

__paused_tasks: set[str] = (source)

Paused tasks produced by set.

__pending_listener_tasks: set[asyncio.Task] = (source)

Pending listener tasks produced by set.

Reactor instance for command execution.

__removed_tasks: set[str] = (source)

Removed tasks produced by set.

__running_tasks: set[str] = (source)

Running tasks produced by set.

Scheduler instance responsible for registering and running tasks.

__scheduler_listeners: dict[SchedulerEvent, Callable] = (source)

Callbacks subscribed to scheduler lifecycle events.

__shutdown_error: BaseException | None = (source)

Failure retained for the caller awaiting shutdown completion.

__shutdown_event = (source)

Notify callers when scheduler shutdown settles.

__shutdown_task: asyncio.Task | None = (source)

Single shutdown operation owned by the current scheduler cycle.

__state: ScheduleStates = (source)

State selected by the maintenance-mode command.

Schedule store for managing job stores.

__tasks: dict[str, TaskEntity] = (source)

Tasks registered for scheduling or lifecycle management.

__tasks_listeners: dict[str, dict[TaskEvent, Callable]] = (source)

Callbacks subscribed to scheduled-task events.

__wait_to_shutdown: float = (source)

Wait to shutdown value used by Schedule.