orionis 0.566.0__py3-none-any.whl → 0.568.0__py3-none-any.whl

orionis/console/base/scheduler.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from orionis.console.contracts.base_scheduler import IBaseScheduler
 from orionis.console.contracts.schedule import ISchedule
-from orionis.console.entities.job_error import JobError
+from orionis.console.entities.scheduler_error import SchedulerError
 from orionis.console.entities.scheduler_paused import SchedulerPaused
 from orionis.console.entities.scheduler_resumed import SchedulerResumed
 from orionis.console.entities.scheduler_shutdown import SchedulerShutdown
@@ -163,17 +163,17 @@ class BaseScheduler(IBaseScheduler):
         """
         pass
 
-    async def onError(self, event: JobError, schedule: ISchedule):
+    async def onError(self, event: SchedulerError, schedule: ISchedule):
         """
         Handles the event triggered when a job encounters an error during execution.
 
-        This method is invoked when a job fails due to an exception. It processes the `JobError`
+        This method is invoked when a job fails due to an exception. It processes the `SchedulerError`
         event and performs any necessary actions, such as logging the error details or notifying
         relevant systems about the failure.
 
         Parameters
         ----------
-        event : JobError
+        event : SchedulerError
             The event object containing details about the job error, including the job ID,
             the exception that occurred, and any relevant metadata.
         schedule : ISchedule

orionis/console/contracts/base_scheduler.py

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 from orionis.console.contracts.schedule import ISchedule
-from orionis.console.entities.job_error import JobError
+from orionis.console.entities.scheduler_error import SchedulerError
 from orionis.console.entities.scheduler_paused import SchedulerPaused
 from orionis.console.entities.scheduler_resumed import SchedulerResumed
 from orionis.console.entities.scheduler_shutdown import SchedulerShutdown
@@ -157,17 +157,17 @@ class IBaseScheduler(ABC):
         pass
 
     @abstractmethod
-    async def onError(self, event: JobError, schedule: ISchedule):
+    async def onError(self, event: SchedulerError, schedule: ISchedule):
         """
         Handles the event triggered when a job encounters an error during execution.
 
-        This method is invoked when a job fails due to an exception. It processes the `JobError`
+        This method is invoked when a job fails due to an exception. It processes the `SchedulerError`
         event and performs any necessary actions, such as logging the error details or notifying
         relevant systems about the failure.
 
         Parameters
         ----------
-        event : JobError
+        event : SchedulerError
             The event object containing details about the job error, including the job ID,
             the exception that occurred, and any relevant metadata.
         schedule : ISchedule

orionis/console/entities/command.py

@@ -12,14 +12,16 @@ class Command(BaseEntity):
     ----------
     obj : Type
         The type or class associated with the command.
-    timestamps : bool
-        Whether timestamps are enabled for this command.
+    method : str, optional
+        The method name to be invoked on the object. Defaults to 'hanldle'.
+    timestamps : bool, optional
+        Whether timestamps are enabled for this command. Defaults to True.
     signature : str
         The signature string representing the command usage.
     description : str
         A brief description of what the command does.
     args : Optional[argparse.ArgumentParser], optional
-        Optional argument parser for command-line arguments.
+        Optional argument parser for command-line arguments. Defaults to None.
 
     Returns
     -------
@@ -30,11 +32,11 @@ class Command(BaseEntity):
     # The type or class associated with the command
     obj: Type
 
-    # The method name to be invoked on the object
+    # The method name to be invoked on the object (default: 'hanldle')
     method: str = 'hanldle'
 
-    # Indicates if timestamps are enabled for this command
-    timestamps: bool
+    # Indicates if timestamps are enabled for this command (default: True)
+    timestamps: bool = True
 
     # The command usage signature
     signature: str
@@ -42,5 +44,5 @@ class Command(BaseEntity):
     # Description of the command's purpose
     description: str
 
-    # Optional argument parser for command-line arguments
+    # Optional argument parser for command-line arguments (default: None)
     args: Optional[argparse.ArgumentParser] = None

orionis/console/entities/event.py

@@ -9,30 +9,37 @@ from orionis.console.contracts.schedule_event_listener import IScheduleEventList
 @dataclass(kw_only=True)
 class Event:
     """
-    Represents an event with scheduling and execution details.
+    Represents a scheduled event with configuration for execution, timing, and event handling.
 
-    Attributes
+    Parameters
     ----------
     signature : str
-        The unique identifier or signature of the event, used to distinguish it from other events.
-    args : Optional[List[str]]
-        A list of arguments associated with the event. Defaults to an empty list if not provided.
-    purpose : Optional[str]
-        A brief description of the event's purpose or intent. Can be None if not specified.
-    random_delay : Optional[int]
-        An optional random delay (in seconds) to be applied before the event is triggered. Can be None.
-    start_date : Optional[datetime]
-        The start date and time for the event. If None, the event starts immediately or based on the trigger.
-    end_date : Optional[datetime]
-        The end date and time for the event. If None, the event does not have a defined end time.
-    trigger : Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]]
-        The trigger mechanism for the event, which determines when and how the event is executed.
-        Can be a CronTrigger, DateTrigger, or IntervalTrigger. Defaults to None.
-    details : Optional[str]
-        Additional details or metadata about the event. Can be None if not specified.
-    listener : Optional[IScheduleEventListener]
-        An optional listener object that implements the IScheduleEventListener interface.
-        This listener can handle event-specific logic. Defaults to None.
+        Unique identifier or signature for the event.
+    args : Optional[List[str]], default: []
+        List of arguments to be passed to the event.
+    purpose : Optional[str], default: None
+        Short description of the event's purpose.
+    random_delay : Optional[int], default: None
+        Random delay in seconds before the event is triggered.
+    start_date : Optional[datetime], default: None
+        The date and time when the event becomes active.
+    end_date : Optional[datetime], default: None
+        The date and time when the event is no longer active.
+    trigger : Optional[Union[CronTrigger, DateTrigger, IntervalTrigger]], default: None
+        Trigger mechanism that determines when the event is executed.
+    details : Optional[str], default: None
+        Additional metadata or information about the event.
+    listener : Optional[IScheduleEventListener], default: None
+        Listener object implementing IScheduleEventListener for event-specific logic.
+    max_instances : int, default: 1
+        Maximum number of concurrent instances allowed for the event.
+    misfire_grace_time : Optional[int], default: None
+        Grace period in seconds for handling misfired events.
+
+    Returns
+    -------
+    Event
+        An instance of the Event class with the specified configuration.
     """
 
     # Unique identifier for the event
@@ -66,4 +73,4 @@ class Event:
     max_instances: int = 1
 
     # Grace time in seconds for misfired events
-    misfire_grace_time : Optional[int] = None
+    misfire_grace_time: Optional[int] = None

orionis/console/entities/event_job.py

@@ -5,56 +5,70 @@ from typing import Any, Callable, Optional, Tuple
 @dataclass(kw_only=True)
 class EventJob:
     """
-    Represents the main properties of a job in APScheduler.
+    Represents the main properties and configuration of a scheduled job in APScheduler.
 
-    Attributes
+    Parameters
     ----------
     id : str
         Unique identifier for the job.
-    name : Optional[str]
-        Human-readable name for the job. Can be None if not specified.
-    func : Callable[..., Any]
-        The function or coroutine to be executed by the job.
-    args : Tuple[Any, ...]
-        Positional arguments to be passed to the function.
-    trigger : Any
-        The trigger that determines the job's execution schedule
-        (e.g., IntervalTrigger, CronTrigger, etc.).
-    executor : str
-        Alias of the executor that will run the job.
-    jobstore : str
-        Alias of the job store where the job is stored.
-    misfire_grace_time : Optional[int]
-        Grace period in seconds for handling missed executions.
-        If None, no grace period is applied.
-    max_instances : int
-        Maximum number of concurrent instances of the job allowed.
-    coalesce : bool
-        Whether to merge pending executions into a single execution.
-    next_run_time : Optional[datetime]
-        The next scheduled execution time of the job. Can be None if the job is paused or unscheduled.
+    code : int, optional
+        Numeric code representing the job status or type. Defaults to 0.
+    name : Optional[str], optional
+        Human-readable name for the job. Defaults to None.
+    func : Callable[..., Any], optional
+        The function or coroutine to be executed by the job. Defaults to None.
+    args : Tuple[Any, ...], optional
+        Positional arguments to be passed to the function. Defaults to empty tuple.
+    trigger : Any, optional
+        The trigger that determines the job's execution schedule (e.g., IntervalTrigger, CronTrigger). Defaults to None.
+    executor : str, optional
+        Alias of the executor that will run the job. Defaults to 'default'.
+    jobstore : str, optional
+        Alias of the job store where the job is stored. Defaults to 'default'.
+    misfire_grace_time : Optional[int], optional
+        Grace period in seconds for handling missed executions. If None, no grace period is applied. Defaults to None.
+    max_instances : int, optional
+        Maximum number of concurrent instances of the job allowed. Defaults to 1.
+    coalesce : bool, optional
+        Whether to merge pending executions into a single execution. Defaults to False.
+    next_run_time : Optional[datetime], optional
+        The next scheduled execution time of the job. Can be None if the job is paused or unscheduled. Defaults to None.
+    exception : Optional[BaseException], optional
+        Exception raised during the last job execution, if any. Defaults to None.
+    traceback : Optional[str], optional
+        String representation of the traceback if an exception occurred. Defaults to None.
+    retval : Optional[Any], optional
+        Return value from the last job execution. Defaults to None.
+    purpose : Optional[str], optional
+        Description of the job's purpose. Defaults to None.
+    start_date : Optional[datetime], optional
+        The earliest possible run time for the job. Defaults to None.
+    end_date : Optional[datetime], optional
+        The latest possible run time for the job. Defaults to None.
+    details : Optional[str], optional
+        Additional details or metadata about the job. Defaults to None.
 
     Returns
     -------
     None
-        This class is a data container and does not return any value.
+        This class is a data container and does not return any value upon instantiation.
     """
-    id: str
-    code: int = 0
-    name: Optional[str] = None
-    func: Callable[..., Any] = None
-    args: Tuple[Any, ...] = ()
-    trigger: Any = None
-    executor: str = 'default'
-    jobstore: str = 'default'
-    misfire_grace_time: Optional[int] = None
-    max_instances: int = 1
-    coalesce: bool = False
-    next_run_time: Optional[datetime] = None
-    exception: Optional[BaseException] = None
-    traceback: Optional[str] = None
-    retval: Optional[Any] = None
-    purpose: Optional[str] = None
-    start_date: Optional[datetime] = None
-    end_date: Optional[datetime] = None
-    details: Optional[str] = None
+    id: str                                         # Unique identifier for the job
+    code: int = 0                                   # Numeric code for job status/type
+    name: Optional[str] = None                      # Human-readable job name
+    func: Callable[..., Any] = None                 # Function or coroutine to execute
+    args: Tuple[Any, ...] = ()                      # Positional arguments for the function
+    trigger: Any = None                             # Scheduling trigger (e.g., interval, cron)
+    executor: str = 'default'                       # Executor alias
+    jobstore: str = 'default'                       # Job store alias
+    misfire_grace_time: Optional[int] = None        # Grace period for missed executions
+    max_instances: int = 1                          # Max concurrent job instances
+    coalesce: bool = False                          # Merge pending executions if True
+    next_run_time: Optional[datetime] = None        # Next scheduled execution time
+    exception: Optional[BaseException] = None       # Exception from last execution
+    traceback: Optional[str] = None                 # Traceback string if exception occurred
+    retval: Optional[Any] = None                    # Return value from last execution
+    purpose: Optional[str] = None                   # Description of job's purpose
+    start_date: Optional[datetime] = None           # Earliest run time
+    end_date: Optional[datetime] = None             # Latest run time
+    details: Optional[str] = None                   # Additional job details or metadata

orionis/console/entities/scheduler_error.py

@@ -5,15 +5,28 @@ from orionis.console.entities.scheduler_event_data import SchedulerEventData
 @dataclass(kw_only=True)
 class SchedulerError(SchedulerEventData):
     """
-    Represents an event triggered when the scheduler is paused.
+    Represents an error event triggered by the scheduler.
 
-    This class is a data structure that inherits from `SchedulerEventData` 
-    and is used to encapsulate information related to the scheduler pause event.
+    This data class extends `SchedulerEventData` and is used to encapsulate
+    information related to errors that occur during scheduler operations.
+    It stores the exception that caused the error and the associated traceback
+    for debugging and logging purposes.
 
     Attributes
     ----------
-    (Inherited from SchedulerEventData)
+    exception : Optional[BaseException]
+        The exception instance that caused the scheduler error, if any.
+    traceback : Optional[str]
+        The traceback string providing details about where the error occurred.
+
+    Returns
+    -------
+    SchedulerError
+        An instance containing details about the scheduler error event.
     """
 
-    exception: Optional[BaseException] = None  # Exception that caused the scheduler error
-    traceback: Optional[str] = None  # Traceback information related to the scheduler error
+    # Exception that caused the scheduler error, if present
+    exception: Optional[BaseException] = None
+
+    # Traceback information related to the scheduler error, if available
+    traceback: Optional[str] = None

orionis/console/entities/scheduler_event_data.py

@@ -3,24 +3,21 @@ from dataclasses import dataclass
 @dataclass(kw_only=True)
 class SchedulerEventData:
     """
-    Represents the data associated with scheduler-related events.
+    Base data structure for scheduler-related events.
 
-    This class serves as a base structure for encapsulating information about
-    events occurring within the scheduler system. It includes a numeric event
-    code to identify the type of event and an optional alias for additional
-    context.
+    This class encapsulates information about events that occur within the scheduler system.
+    It provides a numeric event code to identify the event type and can be extended for
+    additional context as needed.
 
-    Attributes
+    Parameters
     ----------
     code : int
-        A numeric code that uniquely identifies the type of event within the
-        scheduler system.
+        Numeric code that uniquely identifies the type of event within the scheduler system.
 
     Returns
     -------
     SchedulerEventData
-        An instance of the `SchedulerEventData` class containing the event code
-        and optional alias.
+        An instance of SchedulerEventData containing the event code.
     """
 
     # Numeric code representing the type of event

orionis/console/entities/scheduler_paused.py

@@ -6,12 +6,20 @@ class SchedulerPaused(SchedulerEventData):
     """
     Represents an event triggered when the scheduler is paused.
 
-    This class is a data structure that inherits from `SchedulerEventData` 
-    and is used to encapsulate information related to the scheduler pause event.
+    This data class extends `SchedulerEventData` and encapsulates information
+    related to the scheduler pause event, such as the time at which the pause occurred.
 
     Attributes
     ----------
-    (Inherited from SchedulerEventData)
+    time : str
+        The time when the scheduler was paused, formatted as a string.
+    (Other attributes are inherited from SchedulerEventData.)
+
+    Returns
+    -------
+    SchedulerPaused
+        An instance of SchedulerPaused containing information about the pause event.
     """
 
-    time: str  # Time when the scheduler was paused
+    # The time when the scheduler was paused
+    time: str

orionis/console/entities/scheduler_resumed.py

@@ -6,19 +6,19 @@ class SchedulerResumed(SchedulerEventData):
     """
     Represents an event triggered when the scheduler is resumed.
 
-    This class is a specialized data structure that inherits from
-    `SchedulerEventData` and is used to encapsulate information
-    about the resumption of the scheduler.
+    This data class extends `SchedulerEventData` and is used to encapsulate
+    information about the scheduler's resumption event.
 
     Attributes
     ----------
-    (Inherited from SchedulerEventData)
+    time : str
+        The time when the scheduler was resumed.
 
     Returns
     -------
     SchedulerResumed
-        An instance of the `SchedulerResumed` class representing
-        the resumed scheduler event.
+        An instance containing information about the resumed scheduler event.
     """
 
-    time: str  # The time when the scheduler was resumed
+    # The time when the scheduler was resumed
+    time: str

orionis/console/entities/scheduler_shutdown.py

@@ -6,18 +6,26 @@ class SchedulerShutdown(SchedulerEventData):
     """
     Represents an event triggered when the scheduler shuts down.
 
-    This class is a specialized type of `SchedulerEventData` that is used to
-    encapsulate information related to the shutdown of the scheduler.
+    This class extends `SchedulerEventData` and is used to encapsulate
+    information related to the shutdown of the scheduler, such as the
+    shutdown time and the list of tasks present at shutdown.
 
     Attributes
     ----------
-    (No additional attributes are defined in this class. It inherits all attributes
-    from `SchedulerEventData`.)
+    time : str
+        The time when the scheduler was shut down.
+    tasks : list
+        The list of tasks that were scheduled at the time of shutdown.
 
     Returns
     -------
     SchedulerShutdown
-        An instance of the `SchedulerShutdown` class representing the shutdown event.
+        An instance representing the scheduler shutdown event, containing
+        the shutdown time and the list of scheduled tasks.
     """
-    time: str = ""                              # The time when the scheduler started
-    tasks: list = field(default_factory=list)   # List of tasks scheduled at the time of start
+
+    # The time when the scheduler was shut down
+    time: str = ""
+
+    # List of tasks scheduled at the time of shutdown
+    tasks: list = field(default_factory=list)

orionis/console/entities/scheduler_started.py

@@ -4,19 +4,27 @@ from orionis.console.entities.scheduler_event_data import SchedulerEventData
 @dataclass(kw_only=True)
 class SchedulerStarted(SchedulerEventData):
     """
-    Represents an event triggered when the scheduler starts running.
+    Represents the event data generated when the scheduler starts.
 
-    This class is a data structure that inherits from `SchedulerEventData`
-    and is used to encapsulate information about the scheduler's start event.
+    This data class extends `SchedulerEventData` and encapsulates information
+    about the scheduler's start event, such as the start time and the list of
+    tasks scheduled at that moment.
 
     Attributes
     ----------
-    (No additional attributes are defined in this class; it inherits all attributes from `SchedulerEventData`.)
+    time : str
+        The time when the scheduler started.
+    tasks : list
+        The list of tasks that were scheduled at the time the scheduler started.
 
     Returns
     -------
     SchedulerStarted
-        An instance of the `SchedulerStarted` class, representing the scheduler start event.
+        An instance containing the scheduler start event data.
     """
-    time: str = ""                              # The time when the scheduler started
-    tasks: list = field(default_factory=list)   # List of tasks scheduled at the time of start
+
+    # The time when the scheduler started
+    time: str = ""
+
+    # List of tasks scheduled at the time of start
+    tasks: list = field(default_factory=list)

orionis/console/enums/actions.py

@@ -2,42 +2,61 @@ from enum import Enum
 
 class ArgumentAction(Enum):
     """
-    Enumeration for valid argparse action types.
-
-    This enum provides a comprehensive list of all standard action types
-    that can be used with Python's argparse module when defining command
-    line arguments. Each enum member corresponds to a specific behavior
-    for how argument values should be processed and stored.
+    Enumeration of valid action types for use with Python's argparse module.
+
+    This enum defines all standard action types that can be assigned to command-line arguments
+    using argparse. Each member represents a specific way argparse processes and stores argument values.
+
+    Attributes
+    ----------
+    STORE : str
+        Stores the argument value directly.
+    STORE_CONST : str
+        Stores a constant value when the argument is specified.
+    STORE_TRUE : str
+        Stores True when the argument is specified.
+    STORE_FALSE : str
+        Stores False when the argument is specified.
+    APPEND : str
+        Appends each argument value to a list.
+    APPEND_CONST : str
+        Appends a constant value to a list when the argument is specified.
+    COUNT : str
+        Counts the number of times the argument is specified.
+    HELP : str
+        Displays the help message and exits.
+    VERSION : str
+        Displays version information and exits.
 
     Returns
     -------
     str
-        The string value representing the argparse action type.
+        The string value representing the corresponding argparse action type.
     """
 
-    # Store the argument value directly
+    # Stores the argument value directly
     STORE = "store"
 
-    # Store a constant value when the argument is specified
+    # Stores a constant value when the argument is specified
     STORE_CONST = "store_const"
 
-    # Store True when the argument is specified
+    # Stores True when the argument is specified
     STORE_TRUE = "store_true"
 
-    # Store False when the argument is specified
+    # Stores False when the argument is specified
     STORE_FALSE = "store_false"
 
-    # Append each argument value to a list
+    # Appends each argument value to a list
     APPEND = "append"
 
-    # Append a constant value to a list when the argument is specified
+    # Appends a constant value to a list when the argument is specified
     APPEND_CONST = "append_const"
 
-    # Count the number of times the argument is specified
+    # Counts the number of times the argument is specified
     COUNT = "count"
 
-    # Display help message and exit
+    # Displays the help message and exits the program
     HELP = "help"
 
-    # Display version information and exit
+    # Displays version information and exits the program
     VERSION = "version"