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 Schedule(ISchedule): (source)
Constructor: Schedule(reactor, exception_handler, stores)
Register scheduled tasks and coordinate their scheduler integration.
| Method | __add |
Register the configured database or Redis job store. |
| Method | __control |
Report a scheduler control failure and return its error. |
| Method | __create |
Create a supervised asyncio task and retain it until completion. |
| Async Method | __drain |
Await the current listener snapshot without awaiting its shutdown owner. |
| Async Method | __drain |
Collect owned futures and observe failures without abandoning cleanup. |
| Async Method | __finish |
Await native shutdown, job cleanup and late lifecycle listeners. |
| Async Method | __graceful |
Finalize shutdown and preserve failures for waiting callers. |
| Async Method | __handle |
Report a scheduler failure through runtime or legacy handling. |
| Async Method | __handle |
Report a task execution failure independently of event listeners. |
| Method | __init__ |
Initialize scheduler dependencies, task registries, and shutdown state. |
| Async Method | __load |
Cache command signatures exposed by the reactor. |
| Method | __shutdown |
Notify shutdown waiters if the managed shutdown task was cancelled. |
| Async Method | __start |
Build and start one native backend under the lifecycle lock. |
| Method | __suppress |
Disable APScheduler loggers and their message propagation. |
| Async Method | __validate |
Validate fluent task signatures and build their task entities. |
| Method | _dispatch |
Dispatch a scheduler event to its registered listener. |
| Method | _dispatch |
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 | is |
Check whether the scheduler is paused. |
| Method | is |
Check whether the scheduler is running. |
| Method | is |
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 | pause |
Pause a running task by its signature. |
| Method | remove |
Remove all tasks from the scheduler. |
| Method | remove |
Remove a tracked task from the scheduler. |
| Method | resume |
Resume scheduling when the scheduler is paused. |
| Method | resume |
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 |
The Orionis task scheduler has not been started.. |
| Instance Variable | __available |
Available command signatures produced by set. |
| Instance Variable | __boot |
Serialize native scheduler creation and closure. |
| Instance Variable | __config |
Validated configuration used to construct and operate the service. |
| Instance Variable | __exception |
Exception handler for managing errors. |
| Instance Variable | __failure |
Application runtime retained for callbacks outside the starting context. |
| Instance Variable | __fluent |
Task declarations awaiting conversion to scheduler jobs. |
| Instance Variable | __job |
Job store obtained from self.__config.store. |
| Instance Variable | __paused |
Paused tasks produced by set. |
| Instance Variable | __pending |
Pending listener tasks produced by set. |
| Instance Variable | __reactor |
Reactor instance for command execution. |
| Instance Variable | __removed |
Removed tasks produced by set. |
| Instance Variable | __running |
Running tasks produced by set. |
| Instance Variable | __scheduler |
Scheduler instance responsible for registering and running tasks. |
| Instance Variable | __scheduler |
Callbacks subscribed to scheduler lifecycle events. |
| Instance Variable | __shutdown |
Failure retained for the caller awaiting shutdown completion. |
| Instance Variable | __shutdown |
Notify callers when scheduler shutdown settles. |
| Instance Variable | __shutdown |
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 |
Callbacks subscribed to scheduled-task events. |
| Instance Variable | __wait |
Wait to shutdown value used by Schedule. |
Register the configured database or Redis job store.
Leave the in-memory store unchanged when no persistent driver is selected.
| Returns | |
None | Add the selected persistent store to the scheduler. |
| Raises | |
RuntimeError | If persistent-store configuration is missing or its backend is unsupported. |
Report a scheduler control failure and return its error.
| Parameters | |
message:str | Message describing the failed scheduler operation. |
action:str | Control-method name attached to the failure report. |
| Returns | |
RuntimeError | New error carrying the supplied message. |
Create a supervised asyncio task and retain it until completion.
| Parameters | |
coroutine:collections.abc.Coroutine | Coroutine to execute and close if its supervisor never starts. |
| Returns | |
asyncio.Task | Task supervised for failures and removed from the pending set when complete. |
Collect owned futures and observe failures without abandoning cleanup.
| Parameters | |
pending:tuple of asyncio.Future | Owned jobs or listeners whose completion must be collected. |
| Returns | |
None | No return value. |
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 | |
None | Complete native shutdown and owned asynchronous cleanup. |
Finalize shutdown and preserve failures for waiting callers.
| Returns | |
None | Run shutdown, retain any failure, and always notify shutdown waiters. |
| Raises | |
BaseException | If shutdown is cancelled or raises another non-Exception error. |
Self, exception: Exception, *, legacy: bool = True):
(source)
¶
Report a scheduler failure through runtime or legacy handling.
| Parameters | |
exception:Exception | Exception raised by a scheduled operation or event listener. |
legacy:bool, default True | Allow the configured exception handler as a fallback; log instead when False. |
| Returns | |
None | Capture the failure or apply the selected fallback reporting path. |
Report a task execution failure independently of event listeners.
| Parameters | |
exception:BaseException | Execution error reported by the scheduler. |
signature:str | Command signature associated with the failed job. |
| Returns | |
None | Capture the error and use fallback reporting for ordinary exceptions when runtime reporting is unavailable. |
Self, reactor: IReactor, exception_handler: ICatch, stores: IScheduleStore):
(source)
¶
Initialize scheduler dependencies, task registries, and shutdown state.
| Parameters | |
reactor:orionis.console.core.contracts.reactor.IReactor | Command dispatcher used to discover available signatures. |
exceptionorionis.failure.contracts.catch.ICatch | Fallback handler for event-listener failures. |
stores:orionis.console.contracts.store.IScheduleStore | Job-store factory providing the scheduler configuration. |
| Returns | |
None | Store dependencies and prepare a stopped scheduler. |
Cache command signatures exposed by the reactor.
Skip discovery when the signature cache is already populated.
| Returns | |
None | Update the internal set of available command signatures. |
Notify shutdown waiters if the managed shutdown task was cancelled.
| Parameters | |
task:asyncio.Task | Completed shutdown supervisor task. |
| Returns | |
None | Record cancellation and signal completion if shutdown has not done so. |
Disable APScheduler loggers and their message propagation.
| Returns | |
None | Set scheduler component loggers to CRITICAL and disable them. |
Validate fluent task signatures and build their task entities.
| Returns | |
None | Populate the task registry using configured scheduling defaults. |
| Raises | |
ValueError | If a task signature is unavailable in the reactor. |
Dispatch a scheduler event to its registered listener.
| Parameters | |
event:apscheduler.events.SchedulerEvent | Lifecycle event to wrap for the listener. |
| Returns | |
None | Invoke a synchronous listener or supervise an asynchronous listener, reporting failures. Do nothing when no listener is registered. |
Observe task failures and dispatch the matching event listener.
| Parameters | |
event:apscheduler.events.JobEvent | Job event containing a task signature and execution metadata. |
| Returns | |
None | Update removal bookkeeping, report execution failures, and invoke the registered listener when present. |
Initialize and start the scheduler with configured tasks and listeners.
| Returns | |
None | Register job stores, jobs, and event dispatchers, then start scheduling. |
| Raises | |
ValueError | If a task signature is unavailable in the reactor. |
RuntimeError | If a selected job store lacks required configuration or a supported backend, or shutdown is still in progress. |
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:str | Non-empty command signature to schedule. |
args:list[str] or None, optional | Command-line tokens; use an empty list when None. |
purpose:str or None, optional | Human-readable description of the scheduled command. |
| Returns | |
orionis.console.fluent.contracts.task.ITask | Fluent task definition for configuring timing and listeners. |
| Raises | |
RuntimeError | If the scheduler is not stopped. |
TypeError | If the signature is blank or not a string, or arguments are not a list of strings or None. |
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 | |
ValueError | If a task signature is unavailable in the reactor. |
Check whether the scheduler is paused.
| Returns | |
bool | True when the scheduler state is PAUSED, otherwise False. |
Check whether the scheduler is running.
| Returns | |
bool | True when the scheduler state is RUNNING, otherwise False. |
Check whether the scheduler is stopped.
| Returns | |
bool | True when the scheduler state is STOPPED, otherwise False. |
Register or replace a listener for a scheduler lifecycle event.
| Parameters | |
event:orionis.console.enums.events.SchedulerEvent | Scheduler lifecycle event to observe. |
listener:collections.abc.Callable | Synchronous or asynchronous callback receiving a scheduler event entity. |
| Returns | |
typing.Self | This scheduler for chained configuration. |
| Raises | |
RuntimeError | If the scheduler is not stopped. |
TypeError | If event is not a scheduler event or listener is not callable. |
Pause scheduling when the scheduler is running.
| Returns | |
bool | True after pausing the scheduler and updating its state. |
| Raises | |
RuntimeError | If the scheduler is uninitialized, is not running, or cannot be paused. |
Pause a running task by its signature.
| Parameters | |
signature:str | Signature of the running task to pause. |
| Returns | |
bool | True after pausing the job and updating task bookkeeping. |
| Raises | |
RuntimeError | If the scheduler is uninitialized, the task is not running, or the pause operation fails. |
ValueError | If the scheduler cannot find the tracked job. |
Remove all tasks from the scheduler.
| Returns | |
bool | True after removing all jobs and clearing active task bookkeeping. |
| Raises | |
RuntimeError | If the scheduler is uninitialized or the removal operation fails. |
Remove a tracked task from the scheduler.
| Parameters | |
signature:str | Signature of the running or paused task to remove. |
| Returns | |
bool | True after removing the job and updating task bookkeeping. |
| Raises | |
RuntimeError | If the scheduler is uninitialized, the task is not tracked as running or paused, or the removal operation fails. |
ValueError | If the scheduler cannot find the tracked job. |
Resume scheduling when the scheduler is paused.
| Returns | |
bool | True after resuming the scheduler and updating its state. |
| Raises | |
RuntimeError | If the scheduler is uninitialized, is not paused, or cannot be resumed. |
Resume a paused task by its signature.
| Parameters | |
signature:str | Signature of the paused task to resume. |
| Returns | |
bool | True after resuming the job and updating task bookkeeping. |
| Raises | |
RuntimeError | If the scheduler is uninitialized, the task is not paused, or the resume operation fails. |
ValueError | If the scheduler cannot find the tracked job. |
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, optional | Non-negative grace period in seconds. Keep the current period when None; the initial default is 0.5 seconds. |
| Returns | |
None | Start or reuse the managed shutdown task without waiting for completion. |
| Raises | |
TypeError | If wait is negative, a boolean, or neither an integer nor None. |
Wait for shutdown completion and re-raise any retained failure.
| Returns | |
None | Return once shutdown completes successfully. |
| Raises | |
BaseException | If shutdown failed or its task was cancelled. |
The Orionis task scheduler has not been started..
| Value |
|