orionis 0.1.0__py3-none-any.whl

orionis/luminate/contracts/console/runner_interface.py

@@ -0,0 +1,50 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class ICLIRunner(ABC):
+    """
+    Interface for CLIRunner, defining the structure for handling CLI command execution.
+
+    This interface ensures that any implementing class properly processes and executes CLI commands.
+
+    Methods
+    -------
+    handle(signature: str = None, vars: dict = {}, *args, **kwargs) -> Any
+        Processes and executes a CLI command based on provided arguments.
+    """
+
+    @abstractmethod
+    def handle(self, signature: str = None, vars: dict = {}, *args, **kwargs) -> Any:
+        """
+        Processes and executes a CLI command.
+
+        This method:
+        - Determines whether the command is invoked from `sys.argv` or as a function.
+        - Extracts the command signature and arguments.
+        - Executes the command pipeline.
+        - Logs execution status and handles errors.
+
+        Parameters
+        ----------
+        signature : str, optional
+            The command signature (default is None, meaning it is extracted from `sys.argv`).
+        vars : dict, optional
+            Named arguments for the command (default is an empty dictionary).
+        *args
+            Additional arguments for the command.
+        **kwargs
+            Additional keyword arguments for the command.
+
+        Returns
+        -------
+        Any
+            The output of the executed command.
+
+        Raises
+        ------
+        ValueError
+            If no command signature is provided.
+        Exception
+            If an unexpected error occurs during execution.
+        """
+        pass

orionis/luminate/contracts/console/schedule_interface.py

@@ -0,0 +1,317 @@
+
+from typing import Any
+from datetime import datetime
+from abc import ABC, abstractmethod
+
+class ISchedule(ABC):
+    """
+    A class that manages the scheduling of tasks using the APScheduler.
+
+    Attributes
+    ----------
+    scheduler : BackgroundScheduler
+        The background scheduler instance used to schedule tasks.
+    callback : function | None
+        A callback function that will be called when the scheduled task is triggered.
+
+    Methods
+    -------
+    command(signature: str, vars: dict[str, Any] = {}, *args: Any, **kwargs: Any) -> 'Schedule':
+        Defines a command to execute.
+    """
+
+    @abstractmethod
+    def command(self, signature: str, vars: dict[str, Any] = {}, *args: Any, **kwargs: Any):
+        """
+        Defines a Orionis command to be executed.
+
+        Parameters
+        ----------
+        signature : str
+            The signature of the command to execute.
+        vars : dict, optional
+            A dictionary of variables to pass to the command, by default an empty dictionary.
+        *args : Any
+            Additional positional arguments to pass to the command.
+        **kwargs : Any
+            Additional keyword arguments to pass to the command.
+
+        Returns
+        -------
+        Schedule
+            Returns the Schedule instance itself, allowing method chaining.
+        """
+        pass
+
+    @abstractmethod
+    def onceAt(self, date: datetime):
+        """
+        Schedule the defined command to execute every X seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everySeconds(self, seconds: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedule the defined command to execute every X seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everySecond(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every second.
+        """
+        pass
+
+    @abstractmethod
+    def everyTwoSeconds(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every two seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everyFiveSeconds(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every five seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everyTenSeconds(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every ten seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everyFifteenSeconds(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every fifteen seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everyTwentySeconds(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every twenty seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everyThirtySeconds(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every thirty seconds.
+        """
+        pass
+
+    @abstractmethod
+    def everyMinutes(self, minutes: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every X minutes.
+        """
+        pass
+
+    @abstractmethod
+    def everyMinute(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every minute.
+        """
+        pass
+
+    @abstractmethod
+    def everyTwoMinutes(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every two minutes.
+        """
+        pass
+
+    @abstractmethod
+    def everyThreeMinutes(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every three minutes.
+        """
+        pass
+
+    @abstractmethod
+    def everyFourMinutes(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every four minutes.
+        """
+        pass
+
+    @abstractmethod
+    def everyFiveMinutes(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every five minutes.
+        """
+        pass
+
+    @abstractmethod
+    def everyTenMinutes(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every ten minutes.
+        """
+        pass
+
+    @abstractmethod
+    def everyFifteenMinutes(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every fifteen minutes.
+        """
+        pass
+
+    @abstractmethod
+    def everyThirtyMinutes(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every thirty minutes.
+        """
+        pass
+
+    @abstractmethod
+    def hours(self, hours: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every X hours.
+        """
+        pass
+
+    @abstractmethod
+    def hourly(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every hour.
+        """
+        pass
+
+    @abstractmethod
+    def hourlyAt(self, minute: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every hour at a specific minute.
+        """
+        pass
+
+    @abstractmethod
+    def everyOddHour(self, minute: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every odd hour.
+        """
+        pass
+
+    @abstractmethod
+    def everyTwoHours(self, minute: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every two hours.
+        """
+        pass
+
+    @abstractmethod
+    def everyThreeHours(self, minute: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every three hours.
+        """
+        pass
+
+    @abstractmethod
+    def everyFourHours(self, minute: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every four hours.
+        """
+        pass
+
+    @abstractmethod
+    def everySixHours(self, minute: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every six hours.
+        """
+        pass
+
+    @abstractmethod
+    def days(self, days: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every X days.
+        """
+        pass
+
+    @abstractmethod
+    def daily(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute daily at midnight.
+        """
+        pass
+
+    @abstractmethod
+    def dailyAt(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute daily at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def twiceDaily(self, first_hour: int, second_hour: int, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute twice a day at specific hours.
+        """
+        pass
+
+    @abstractmethod
+    def monday(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every Monday at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def tuesday(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every tuesday at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def wednesday(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every wednesday at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def thursday(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every thursday at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def friday(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every friday at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def saturday(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every saturday at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def sunday(self, at: str, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute every sunday at a specific time.
+        """
+        pass
+
+    @abstractmethod
+    def weekly(self, start_date: datetime = None, end_date: datetime = None):
+        """
+        Schedules the defined command to execute weekly on Sunday at midnight.
+        """
+        pass
+
+    @abstractmethod
+    def start(self):
+        """
+        Starts the scheduler and stops automatically when there are no more jobs.
+        """
+        pass

orionis/luminate/contracts/console/task_manager_interface.py

@@ -0,0 +1,37 @@
+from abc import ABC, abstractmethod
+from orionis.luminate.console.tasks.scheduler import Schedule
+
+class ITaskManager(ABC):
+    """
+    Abstract base class that defines the interface for managing tasks.
+
+    This class provides an abstract method `schedule` that must be implemented by any
+    subclass to define how tasks are scheduled.
+
+    Methods
+    -------
+    schedule(schedule: Schedule) -> None
+        Schedules a task based on the provided `Schedule` instance.
+    """
+
+    @abstractmethod
+    def schedule(self, schedule: Schedule) -> None:
+        """
+        Schedules a task based on the given `Schedule` instance.
+
+        This method is abstract and must be implemented by a subclass to define
+        the specific scheduling logic.
+
+        Parameters
+        ----------
+        schedule : Schedule
+            An instance of the `Schedule` class, which contains the details of
+            when and how the task should be executed.
+
+        Returns
+        -------
+        None
+            This method does not return anything, but it is expected to schedule
+            the task as defined by the `schedule` object.
+        """
+        pass

orionis/luminate/contracts/facades/env_interface.py

@@ -0,0 +1,64 @@
+from abc import ABC, abstractmethod
+from typing import Optional, Dict
+
+class IEnv(ABC):
+    """
+    Interface for managing environment variables from a .env file.
+    """
+
+    @abstractmethod
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Retrieve the value of an environment variable.
+
+        Parameters
+        ----------
+        key : str
+            The key of the environment variable.
+        default : Optional[str], optional
+            Default value if the key does not exist, by default None.
+
+        Returns
+        -------
+        Optional[str]
+            The value of the environment variable or the default value.
+        """
+        pass
+
+    @abstractmethod
+    def set(self, key: str, value: str) -> None:
+        """
+        Set the value of an environment variable in the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The key of the environment variable.
+        value : str
+            The value to set.
+        """
+        pass
+
+    @abstractmethod
+    def unset(self, key: str) -> None:
+        """
+        Remove an environment variable from the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The key of the environment variable to remove.
+        """
+        pass
+
+    @abstractmethod
+    def all(self) -> Dict[str, str]:
+        """
+        Retrieve all environment variable values from the .env file.
+
+        Returns
+        -------
+        Dict[str, str]
+            A dictionary of all environment variables and their values.
+        """
+        pass

orionis/luminate/contracts/facades/log_interface.py

@@ -0,0 +1,48 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+import logging
+from orionis.luminate.contracts.log.logger_interface import ILogger
+
+class ILogFacade(ABC):
+    """
+    Facade interface for simplified access to logging operations.
+
+    Methods
+    -------
+    info(message: str) -> None
+        Logs an informational message.
+    error(message: str) -> None
+        Logs an error message.
+    success(message: str) -> None
+        Logs a success message (treated as info).
+    warning(message: str) -> None
+        Logs a warning message.
+    debug(message: str) -> None
+        Logs a debug message.
+    configure(path: Optional[str], level: int) -> ILogger
+        Configures and returns the logger instance.
+    """
+
+    @abstractmethod
+    def info(self, message: str) -> None:
+        pass
+
+    @abstractmethod
+    def error(self, message: str) -> None:
+        pass
+
+    @abstractmethod
+    def success(self, message: str) -> None:
+        pass
+
+    @abstractmethod
+    def warning(self, message: str) -> None:
+        pass
+
+    @abstractmethod
+    def debug(self, message: str) -> None:
+        pass
+
+    @abstractmethod
+    def configure(self, path: Optional[str] = None, level: int = logging.INFO) -> ILogger:
+        pass

orionis/luminate/contracts/facades/paths_interface.py

@@ -0,0 +1,141 @@
+from abc import ABC, abstractmethod
+
+class IPath(ABC):
+
+    @abstractmethod
+    def _resolve_directory(directory: str, file: str = None):
+        """
+        Internal helper function to resolve an absolute path for a given directory.
+
+        Parameters
+        ----------
+        directory : str
+            The base directory to resolve the path from.
+        file : str, optional
+            The relative file path inside the directory (default is an empty string).
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved absolute path wrapped in a SkeletonPath object.
+        """
+        pass
+
+    @abstractmethod
+    def app(file: str = None):
+        """
+        Returns the absolute path for a file inside the 'app' directory.
+
+        Parameters
+        ----------
+        file : str, optional
+            The relative file path inside the 'app' directory.
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved path wrapped in a SkeletonPath object.
+        """
+        pass
+
+    @abstractmethod
+    def config(file: str = None):
+        """
+        Returns the absolute path for a file inside the 'config' directory.
+
+        Parameters
+        ----------
+        file : str, optional
+            The relative file path inside the 'config' directory.
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved path wrapped in a SkeletonPath object.
+        """
+        pass
+
+    @abstractmethod
+    def database(file: str = None):
+        """
+        Returns the absolute path for a file inside the 'database' directory.
+
+        Parameters
+        ----------
+        file : str, optional
+            The relative file path inside the 'database' directory.
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved path wrapped in a SkeletonPath object.
+        """
+        pass
+
+    @abstractmethod
+    def resource(file: str = None):
+        """
+        Returns the absolute path for a file inside the 'resource' directory.
+
+        Parameters
+        ----------
+        file : str, optional
+            The relative file path inside the 'resource' directory.
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved path wrapped in a SkeletonPath object.
+        """
+        pass
+
+    @abstractmethod
+    def routes(file: str = None):
+        """
+        Returns the absolute path for a file inside the 'routes' directory.
+
+        Parameters
+        ----------
+        file : str, optional
+            The relative file path inside the 'routes' directory.
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved path wrapped in a SkeletonPath object.
+        """
+        pass
+
+    @abstractmethod
+    def storage(file: str = None):
+        """
+        Returns the absolute path for a file inside the 'storage' directory.
+
+        Parameters
+        ----------
+        file : str, optional
+            The relative file path inside the 'storage' directory.
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved path wrapped in a SkeletonPath object.
+        """
+        pass
+
+    @abstractmethod
+    def tests(file: str = None):
+        """
+        Returns the absolute path for a file inside the 'tests' directory.
+
+        Parameters
+        ----------
+        file : str, optional
+            The relative file path inside the 'tests' directory.
+
+        Returns
+        -------
+        SkeletonPath
+            The resolved path wrapped in a SkeletonPath object.
+        """
+        pass

orionis/luminate/contracts/facades/tests_interface.py

@@ -0,0 +1,33 @@
+from abc import ABC, abstractmethod
+
+class IUnitTests(ABC):
+    """
+    Interface for executing unit tests in a specified directory.
+
+    This class defines the abstract structure for any unit test executor,
+    enforcing the implementation of the 'execute' method in any subclass.
+
+    Methods
+    -------
+    execute(pattern: str) -> dict
+        Executes the unit tests in the 'tests' directory and subdirectories,
+        using a file pattern for filtering test files.
+    """
+
+    @abstractmethod
+    def execute(pattern='test_*.py') -> dict:
+        """
+        Executes the unit tests in the 'tests' directory and its subdirectories
+        by filtering test files based on a specified pattern.
+
+        Parameters
+        ----------
+        pattern : str, optional
+            The pattern to filter test files (default is 'test_*.py').
+
+        Returns
+        -------
+        dict
+            A dictionary containing the results of the executed tests.
+        """
+        pass